Come utilizzare le API di Sitata per determinare le restrizioni di viaggio per i viaggiatori

Molti di voi potrebbero non saperlo, ma le prime fondamenta di Sitata furono costruite per il rilevamento precoce delle malattie. Infatti, la nostra fondatrice tenne un discorso TedX già nel 2016 sul perché dobbiamo avvisare i viaggiatori per prevenire la diffusione delle malattie. Quindi non sorprende che siamo venuti a conoscenza del COVID-19, segnalato come un insolito gruppo di casi di polmonite all’inizio di dicembre 2019. Il 2 gennaio 2020, il nostro team sanitario decise che dovevamo emettere un primo avviso ai nostri viaggiatori e partner commerciali. Questo avvenne addirittura alcuni giorni prima dell’Organizzazione Mondiale della Sanità!

Durante l’inevitabile evoluzione della situazione, abbiamo avuto un’intuizione. La malattia si stava diffondendo così rapidamente che era chiaro per noi che la risposta globale sarebbe stata, nel migliore dei casi, caotica. Ogni paese avrebbe emanato i propri regolamenti e le proprie regole per controllare la diffusione. Ciò avrebbe inevitabilmente creato scompiglio in tutto il mondo e sarebbe stata un’enorme fonte di confusione per coloro che desideravano ancora viaggiare. Avevamo ragione e decidemmo di fare qualcosa al riguardo. Sitata è stata una delle prime aziende al mondo a creare un’API dedicata e un servizio per tracciare i cambiamenti nelle restrizioni di viaggio e nei requisiti d’ingresso a seguito del COVID-19. Grazie a un avanzato sistema software di rilevamento eventi e a un team di analisti specializzati, avevamo già tutti gli strumenti e i processi necessari per farlo.

Dal lancio di questo nuovo servizio, diverse organizzazioni hanno tratto vantaggio dai dati a beneficio dei propri clienti, tra cui Eddy Travels, Flight Centre ed Etihad Airways; altri annunci seguiranno a breve! Per aiutare un maggior numero di organizzazioni focalizzate sui viaggi a beneficiare di questa offerta, abbiamo dettagliato di seguito una serie di esempi per spiegare come utilizzare l’API per vari casi d’uso. Speriamo che queste spiegazioni vi aiutino a far partire le vostre iniziative.

Requisiti d’Ingresso

Le prime domande che un viaggiatore si pone sono senza dubbio: “Posso andarci?” e “Dovrò fare la quarantena?”, quindi è un buon punto di partenza. Abbiamo creato il dataset dei requisiti d’ingresso per rispondere alle difficili domande di tipo “sì/no” riguardanti l’ingresso in un paese o regione.

Al momento della stesura, questo dataset includeva le seguenti dieci categorie distinte:

• Un residente può entrare nel paese?
• Uno straniero può entrare nel paese?
• È consentito il transito attraverso il paese?
• È richiesto un test all’arrivo (insorgenza di malattia)?
• È consentito un certificato di test (insorgenza di malattia)?
• È necessaria una quarantena all’arrivo (insorgenza di malattia)?
• È richiesta la vaccinazione?
• È richiesta un’assicurazione?
• È richiesto un certificato di test?
• È richiesto un modulo di registrazione? (sanitario o altro)

Ogni categoria può avere uno dei seguenti valori:

• Sì
• Sì, con eccezioni
• No
• No, tranne eccezioni

Sebbene la stragrande maggioranza dei valori siano “sì” e “no”, la situazione sul campo non è sempre così semplice. A volte ci sono regole davvero strane e folli che vari governi hanno messo in atto e che richiedono i tipi di valori “con eccezioni”.

Un requisito d’ingresso è essenzialmente un documento che registra un insieme di regole imposte da un attore contro uno o più altri paesi o regioni. L’attore può essere un paese, uno stato o persino un comune nella nostra architettura dei dati. Nel complesso, Sitata copre attualmente i dati a livello nazionale. Tuttavia, abbiamo alcuni record a livello statale/provinciale per alcune regioni, come gli Stati Uniti e altri.

Qualsiasi record che abbia un valore nei campi **origin_country_division_id** o **origin_country_region_id** è rispettivamente a livello statale o a livello comunale. Se desiderate dati più granulari, contattateci e possiamo discutere il vostro caso d’uso.

Prendetevi del tempo per familiarizzare con la struttura dei dati dei requisiti d’ingresso consultando la nostra documentazione API qui.

Una parte della struttura dei dati è leggermente confusa, ovvero il nostro uso del termine “origine”. Questa confusione deriva dal fatto che gli sviluppatori spesso considerano l’origine come il luogo di provenienza o di partenza. Tuttavia, ciò che intendiamo con “origine” è in realtà l’origine della regola imposta ad altri, cioè il paese o la regione che ha creato la restrizione.

Un altro punto importante da notare è come funziona la nostra lista dei paesi interessati. Se affected_countries è vuota, dovrebbe essere interpretata come una regola globale, cioè tutti i paesi sono interessati.

Alcuni Esempi

Come avrete visto nella documentazione, ci sono diversi modi per recuperare i dati dall’API. Di seguito, esamineremo alcuni dei casi d’uso più comuni.

Come ottenere i requisiti tra due paesi?

Ci sono diversi modi per fare questo tipo di richiesta. La versione più semplice è utilizzare i parametri **destination** e **departure**. Questi parametri accettano codici ISO 3166-1 alpha-2 come input.

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

La risposta includerà tutti i requisiti (a livello nazionale e statale) necessari da comprendere per il viaggiatore che parte dal paese di partenza e viaggia verso il paese di destinazione.

E se voglio dati a livello statale?

Sitata ha dati a livello statale per alcune regioni. Saprete che una voce specifica è per uno stato se il campo origin_country_division ha un valore. Potete anche filtrare per recuperare solo dati a livello statale utilizzando il parametro **destination_country_division**. Si aspetta un valore ISO_3166-2. Ad esempio, US-TX per il Texas, USA.

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

Notate che potrebbe essere più semplice cercare per paese, quindi filtrare i dati per stato per vedere se esistono, e utilizzarli se esistono.

Come posso ottenere i requisiti tra due aeroporti?

Proprio come per i paesi, l’API di Sitata può restituire i risultati tra due aeroporti. I parametri departure_airport e destination_airport utilizzano codici ICAO o IATA per filtrare i risultati. La risposta includerà tutte le restrizioni (a livello nazionale e statale) necessarie da comprendere per il viaggiatore che parte dal corrispondente paese di partenza e si reca nel paese di destinazione.

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

La risposta includerà tutte le restrizioni (a livello nazionale e statale) necessarie da comprendere per il viaggiatore che parte dal paese di partenza e si reca nel paese di destinazione.

E se ho solo informazioni sulla città?

Sitata ha scelto di non rispondere a richieste basate su un nome di città specifico, poiché ciò potrebbe portare a conflitti e confusione. Invece, abbiamo scelto di accettare le richieste alla nostra API tramite coordinate di latitudine e longitudine, il che non produce ambiguità nel nostro set di risultati. I parametri sono 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 risolvete le vostre città in base alle località e fate richieste basate sulle coordinate, la nostra API risponderà con tutte le restrizioni (a livello nazionale e statale) necessarie da comprendere per il viaggiatore che parte dal paese di partenza e si reca nel paese di destinazione.

Informazioni Aggiuntive

Per alcuni tipi di requisiti d’ingresso, potrebbero esserci dati aggiuntivi associati in un campo di tipo metadati chiamato extras. Questo campo è una mappatura chiave/valore di vari elementi di informazione aggiuntiva per un requisito specifico.

Qual è il numero di giorni di quarantena?

Questa voce di dati è soggetta al requisito d’ingresso tipo 5. In questa voce, la mappatura **extras** conterrà un campo chiamato quarantine_days che conterrà un numero intero per il numero di giorni di quarantena imposti.

Qual è il numero di ore prima dell’ingresso per un test covid negativo?

Questa voce di dati è soggetta al requisito d’ingresso tipo 8. In questa voce, la mappatura **extras** conterrà un campo chiamato entry_hours che conterrà un numero intero per il numero di ore entro le quali un test covid negativo è valido prima dell’ingresso.

Fatecelo Sapere

Crediamo di avere uno strumento molto robusto che probabilmente soddisferà tutte le vostre esigenze per aiutare i vostri viaggiatori a capire cosa potrebbero incontrare lungo il percorso. Se avete un caso d’uso specifico che non trattiamo, fatecelo sapere!

Aspettate… c’è di più!

Questo post fa parte di una serie in due parti che spiega come interagire con l’API di Sitata per le informazioni sui requisiti d’ingresso e le restrizioni di viaggio. Finora abbiamo parlato dei requisiti d’ingresso che descrivono i tipi di condizioni rigide di tipo sì/no necessarie per entrare in un paese o regione, ma non abbiamo ancora parlato di cosa succede all’interno del paese. Una cosa è sapere come entrare in un paese, un’altra è capire se è possibile spostarsi all’interno del paese o visitare le spiagge o se c’è un coprifuoco obbligatorio.

Restate sintonizzati per il secondo articolo che approfondirà la nostra serie di dati sulle restrizioni di viaggio. Suggerimento: è quasi identico, quindi nel frattempo potete sempre consultare la nostra documentazione API.