Como usar as APIs da Sitata para determinar as restrições de viagem para viajantes

Muitos de vocês podem não saber, mas os primeiros fundamentos da Sitata foram construídos para a detecção precoce de doenças. Na verdade, nosso fundador tem uma palestra TedX de 2016 sobre por que precisamos alertar os viajantes para ajudar a prevenir a propagação de doenças. Não deve ser surpresa, então, que tomamos conhecimento da COVID-19 quando um aglomerado incomum de casos de pneumonia foi relatado no início de dezembro de 2019. Em 2 de janeiro de 2020, nossa equipe de saúde determinou que deveríamos emitir nosso primeiro alerta para nossos viajantes e parceiros comerciais. Isso foi dias antes até mesmo da Organização Mundial da Saúde!

Durante a inevitável repercussão, tivemos uma epifania. A doença estava se espalhando tão rápido que ficou claro que a resposta global seria caótica na melhor das hipóteses. Cada país promulgaria seu próprio conjunto de regulamentos e regras para controlar a propagação. Isso inevitavelmente causaria estragos nas viagens globais e seria uma enorme fonte de confusão para aqueles que ainda desejassem viajar. Estávamos certos e nos propusemos a fazer algo a respeito. A Sitata foi uma das primeiras empresas do mundo a criar uma API dedicada e um serviço de monitoramento para mudanças nas restrições de viagem e requisitos de entrada como resultado da COVID-19. Com um sistema de software avançado para detecção de eventos e uma equipe dedicada de analistas, já tínhamos todas as ferramentas e processos certos para fazê-lo.

Desde o lançamento deste novo serviço, tivemos uma variedade de organizações aproveitando os dados em benefício de seus próprios clientes, incluindo Eddy Travels, Flight Centre e Etihad Airways; e há mais a serem anunciados em breve! Para ajudar mais organizações focadas em viagens a se beneficiarem desta oferta, detalhamos abaixo uma série de exemplos para ajudar a explicar como usar a API para uma variedade de casos de uso. Espero que essas explicações ajudem você a iniciar suas próprias iniciativas.

Requisitos de Entrada

Sem dúvida, as primeiras perguntas que um viajante faz são “posso ir para lá?” e “serei colocado em quarentena?”, então este é um bom lugar para começar. Criamos o conjunto de dados de Requisitos de Entrada para responder aos difíceis “sim/não” das perguntas relacionadas à entrada em um país ou região.

No momento da redação, este conjunto de dados incluía as seguintes 10 categorias distintas:

• Um residente pode entrar no país?
• Um estrangeiro pode entrar no país?
• O trânsito pelo país é permitido?
• Um teste na chegada é obrigatório (surto de doença)?
• Um certificado de teste é permitido (surto de doença)?
• Uma quarentena na chegada é obrigatória (surto de doença)?
• Uma vacina é obrigatória?
• Um seguro é obrigatório?
• Um certificado de teste é obrigatório?
• Um formulário de registro é obrigatório? (saúde ou outro)

Cada categoria pode ter um dos seguintes valores:

• Sim
• Sim, com exceções
• Não
• Não, com exceções

Embora a grande maioria dos valores sejam “sim” e “não”, a situação no terreno nem sempre é tão simples. Às vezes há regras verdadeiramente estranhas e malucas que vários governos implementaram que exigem os tipos de valores “com exceções”.

Um requisito de entrada é essencialmente um registro que documenta um conjunto de regras impostas por um agente contra um ou vários países ou regiões. O agente pode ser um país, estado ou até município em nossa arquitetura de dados. Em geral, a Sitata cobre dados em nível de país atualmente. No entanto, temos alguns registros estaduais/provinciais para regiões selecionadas, como os Estados Unidos e outros.

Qualquer registro que tenha uma entrada no campo **origin_country_division_id** ou **origin_country_region_id** é de nível estadual ou municipal, respectivamente. Se você deseja dados mais granulares, por favor entre em contato e podemos discutir seu caso de uso.

Por favor, reserve um tempo para se familiarizar com a estrutura de dados dos Requisitos de Entrada dando uma olhada em nossa documentação da API aqui.

Uma parte um pouco confusa sobre a estrutura dos dados é nosso uso do termo “origem”. Isso é confuso porque os desenvolvedores muitas vezes pensam que a origem é o local de origem ou partida. No entanto, o que queremos dizer com origem é na verdade a origem da regra imposta a outros, ou seja, o país ou região que criou a restrição.

Outro ponto importante a notar é como nossa lista de países afetados funciona. Se affected_countries estiver vazia, deve ser interpretada como uma regra global. Ou seja, todos os países são afetados.

Alguns Exemplos

Como você deve ter visto na documentação, há várias maneiras de recuperar dados da API. Vamos ver alguns dos casos de uso mais comuns a seguir.

Como posso obter os requisitos entre dois países?

Há algumas maneiras de fazer esse tipo de solicitação. A versão mais simples é usar os parâmetros **destination** e **departure**. Esses parâmetros aceitam códigos ISO 3166-1 alfa-2 como entradas.

GET https://www.sitata.com/api/v2/entry_requirements?departure=DE&destination=IN

A resposta incluirá todos os requisitos (em nível de país e estado) necessários para entender para o viajante que parte do país de partida e viaja para o país de destino.

E se eu quiser dados em nível estadual?

A Sitata tem dados em nível estadual para certas regiões. Você saberá que uma entrada específica é para um estado se o campo **origin_country_division_id** tiver um valor. Você também pode filtrar para recuperar apenas dados em nível estadual usando o parâmetro **destination_country_division**. Ele espera um valor ISO_3166-2. Por exemplo, US-TX para o Texas, EUA.

GET https://www.sitata.com/api/v2/entry_requirements?departure=DE&destination_country_division=IN-AP

Observe que pode ser mais simples consultar por país e depois filtrar pelos dados estaduais para ver se eles existem e usá-los se existirem.

Como posso obter os requisitos entre dois aeroportos?

Assim como no caso dos países, a API da Sitata pode retornar resultados entre dois aeroportos. Os parâmetros **departure_airport** e **destination_airport** usam códigos ICAO ou IATA para filtrar os resultados. A resposta incluirá todas as restrições (em nível de país e estado) necessárias para entender para o viajante que parte do país de partida correspondente e viaja para o país de destino.

GET https://www.sitata.com/api/v2/entry_requirements?departure_airport=MUC&destination_airport=BOM

A resposta incluirá todas as restrições (em nível de país e estado) necessárias para entender para o viajante que parte do país de partida e viaja para o país de destino.

E se eu só tiver informações da cidade?

A Sitata optou por não acomodar consultas por um nome de cidade específico porque isso poderia levar a conflitos e confusão. Em vez disso, optamos por acomodar consultas à nossa API por coordenadas de latitude e longitude, o que não produz nenhuma ambiguidade em nosso conjunto de resultados. Os parâmetros são **departure_lat**, **departure_lng**, **destination_lat** e **destination_lng**.

GET https://www.sitata.com/api/v2/entry_requirements?departure_lat=48.13743&departure_lng=11.57549&destination_lat=19.0760&destination_lng=72.8777

Se você resolver suas cidades para os locais e consultar com base nas coordenadas, nossa API responderá com todas as restrições (em nível de país e estado) necessárias para entender para o viajante que parte do país de partida e viaja para o país de destino.

Dados Adicionais

Para alguns tipos de requisitos de entrada, pode haver dados adicionais associados em um campo do tipo metadados chamado **extras**. Este campo é um mapeamento chave/valor de vários bits extras de informação para um requisito específico.

Qual é o número de dias de quarentena?

Esta entrada de dados está sujeita ao requisito de entrada tipo 5. Nesta entrada, o mapeamento **extras** conterá um campo chamado **quarantine_days** que conterá um número inteiro para a quantidade de dias de quarentena impostos.

Qual é o número de horas antes da entrada para um teste de COVID negativo?

Esta entrada de dados está sujeita ao requisito de entrada tipo 8. Nesta entrada, o mapeamento **extras** conterá um campo chamado **entry_hours** que conterá um número inteiro para a quantidade de horas que um teste COVID negativo é permitido antes da entrada.

Conte-nos

Acreditamos que temos uma API muito robusta que provavelmente atende a todas as suas necessidades para ajudar seus viajantes a entender o que provavelmente encontrarão no caminho. Se você tem um caso de uso específico que não estamos abordando, por favor, nos avise!

Espere… tem mais!

Esta postagem faz parte de uma série de duas partes que explica como interagir com a API da Sitata para requisitos de entrada e informações sobre restrições de viagem. Até agora falamos sobre os Requisitos de Entrada que delineiam os tipos de requisitos rígidos sim/não necessários para entrar em um país ou região, mas também não falamos sobre o que acontece dentro do país. Uma coisa é saber sobre a entrada em um país, e outra é entender se é possível se locomover pelo país ou visitar as praias ou se há um toque de recolher obrigatório.

Fique ligado para o segundo post que mergulhará em nosso conjunto de dados de Restrição de Viagem. Dica - é quase idêntico, então você sempre pode dar uma olhada em nossa documentação da API enquanto isso.