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 la rilevazione precoce delle malattie. Infatti, il nostro fondatore ha un intervento TedX del 2016 proprio su perché dobbiamo avvertire i viaggiatori per aiutare a prevenire la diffusione delle malattie. Non dovrebbe quindi sorprendere che abbiamo individuato il COVID-19 quando fu segnalato come un insolito gruppo di casi di polmonite all’inizio di dicembre 2019. Entro il 2 gennaio 2020, il nostro team sanitario decise di emettere il nostro primo avviso per i nostri viaggiatori e partner commerciali. Questo avvenne giorni prima persino dell’Organizzazione Mondiale della Sanità!

Durante l’inevitabile reazione a catena, abbiamo avuto un’illuminazione. La malattia si stava diffondendo così rapidamente che ci era chiaro che la risposta globale sarebbe stata caotica nella migliore delle ipotesi. Ogni paese avrebbe emanato il proprio insieme di regolamenti e regole su come controllare la diffusione. Ciò avrebbe inevitabilmente creato il caos nei viaggi globali e sarebbe stata una grande fonte di confusione per coloro che desideravano ancora viaggiare. Avevamo ragione e ci siamo messi a fare qualcosa al riguardo. Sitata è stata una delle prime aziende al mondo a creare un’API dedicata e un servizio di monitoraggio per i cambiamenti nelle restrizioni di viaggio e nei requisiti d’ingresso a causa del COVID-19. Con un sistema software avanzato per il rilevamento di eventi e un team dedicato di analisti, avevamo già tutti gli strumenti e i processi giusti per farlo.

Dal lancio di questo nuovo servizio, varie organizzazioni hanno sfruttato i dati a beneficio dei propri clienti, tra cui Eddy Travels, Flight Centre ed Etihad Airways; e altre saranno annunciate presto! Per aiutare più organizzazioni focalizzate sul viaggio a beneficiare di questa offerta, abbiamo scritto in dettaglio di seguito una serie di esempi per spiegare come utilizzare l’API per vari casi d’uso. Spero che queste spiegazioni vi aiutino a far decollare le vostre iniziative.

Requisiti d’Ingresso

Senza dubbio, le prime domande che un viaggiatore si pone sono “posso andarci?” e “sarò messo in quarantena?” e quindi questo è un buon punto di partenza. Abbiamo creato il set di dati dei Requisiti d’Ingresso per rispondere alle domande di tipo “sì/no” riguardanti l’ingresso in un paese o regione.

Al momento della stesura, questo set di dati includeva le seguenti 10 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 (epidemia di malattia)?
• È consentito un certificato di test (epidemia di malattia)?
• È richiesta la quarantena all’arrivo (epidemia di malattia)?
• È richiesta la vaccinazione?
• È richiesta un’assicurazione?
• È richiesto un certificato di test?
• È richiesto un modulo d’ingresso? (sanitario o altro)

Ogni categoria può avere uno dei seguenti valori:

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

Sebbene la stragrande maggioranza dei valori sia “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, il che rende necessari i tipi di valore “con eccezioni”.

Un Requisito d’Ingresso è essenzialmente un record che documenta un insieme di regole imposte da un attore contro uno o più altri paesi o regioni. L’attore potrebbe essere un paese, uno stato o persino un comune nella nostra architettura dei dati. In generale, Sitata copre attualmente dati a livello nazionale. Tuttavia, abbiamo alcuni record statali/provinciali per regioni selezionate come gli Stati Uniti e altre.

Qualsiasi record che ha una voce nel campo **origin_country_division_id** o **origin_country_region_id** è rispettivamente a livello statale o comunale. Se desiderate dati più granulari disponibili, contattateci e possiamo parlare del vostro caso d’uso.

Prendetevi un po’ di tempo per familiarizzare con la struttura dei dati dei Requisiti d’Ingresso dando un’occhiata alla nostra documentazione API qui.

Una parte leggermente confusa della struttura dei dati è il nostro uso del termine “origin”. Questo è confondente perché spesso gli sviluppatori pensano all’origine come al luogo di origine o di partenza. Tuttavia, ciò che intendiamo con origine è in realtà l’origine della regola imposta agli 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 potreste aver visto dalla documentazione, ci sono diversi modi per recuperare dati dall’API. Di seguito esamineremo alcuni dei casi d’uso più comuni.

Come recupero i requisiti tra due paesi?

Ci sono un paio di 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 in partenza dal paese di partenza e in viaggio verso il paese di destinazione.

E se voglio dati a livello statale?

Sitata ha dati a livello statale per alcune regioni. Saprete che una particolare voce è 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, Stati Uniti.

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

Notate che potrebbe essere più semplice interrogare per paese e poi filtrare per dati statali per vedere se tali dati esistono, e utilizzarli se esistono.

Come recupero i requisiti tra due aeroporti?

Proprio come per i paesi, l’API di Sitata può restituire 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 in partenza dal corrispondente paese di partenza e in viaggio verso il 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 in partenza dal paese di partenza e in viaggio verso il paese di destinazione.

E se ho solo informazioni sulla città?

Sitata ha scelto di non accogliere query per un particolare nome di città perché ciò potrebbe causare conflitti e confusione. Invece, abbiamo scelto di consentire l’interrogazione della nostra API tramite coordinate di latitudine e longitudine, che non producono 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 posizioni e interrogate in base alle coordinate, la nostra API risponderà con tutte le restrizioni (a livello nazionale e statale) necessarie da comprendere per il viaggiatore in partenza dal paese di partenza e in viaggio verso il paese di destinazione.

Dati Extra

Per alcuni tipi di Requisiti d’Ingresso, potrebbero esserci dati extra associati in un campo di tipo metadati chiamato extras. Questo campo è una mappatura chiave/valore di varie informazioni extra per un particolare requisito.

Qual è il numero di giorni di quarantena?

Questa voce di dati rientra nel requisito d’ingresso tipo 5. In questa voce, la mappatura **extras** conterrà un campo chiamato quarantine_days che conterrà un 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 rientra nel requisito d’ingresso tipo 8. In questa voce, la mappatura **extras** conterrà un campo chiamato entry_hours che conterrà un intero per il numero di ore entro le quali un test covid negativo è consentito prima dell’ingresso.

Fatecelo sapere

Pensiamo di avere un sistema molto robusto che probabilmente soddisferà tutte le vostre esigenze per aiutare i vostri viaggiatori a capire cosa probabilmente incontreranno lungo il percorso. Se avete un caso d’uso particolare che non stiamo affrontando, fatecelo sapere!

Aspetta… c’è di più!

Questo articolo 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 delineano i requisiti di tipo sì/no necessari per entrare in un paese o regione, ma non abbiamo parlato di cosa succede all’interno del paese. Una cosa è sapere se si può entrare in un paese, un’altra è capire se è possibile spostarsi nel paese, visitare le spiagge o se c’è un coprifuoco obbligatorio.

Restate sintonizzati per il secondo post che approfondirà il nostro set di dati sulle Restrizioni di Viaggio. Suggerimento: è quasi identico, quindi nel frattempo potete sempre dare un’occhiata alla nostra documentazione API.