Hoe je de Sitata API's kunt gebruiken om reisbeperkingen voor reizigers te bepalen

Velen van jullie weten het misschien niet, maar de eerste fundamenten van Sitata werden gebouwd voor de vroege detectie van ziekten. Onze oprichter heeft zelfs een TedX-talk uit 2016 over waarom we reizigers moeten waarschuwen om de verspreiding van ziekten te helpen voorkomen. Het zal dan ook geen verrassing zijn dat we op de hoogte waren van COVID-19 toen er begin december 2019 melding werd gemaakt van een ongebruikelijke cluster van longontstekinggevallen. Op 2 januari 2020 besloot ons gezondheidsteam dat we onze eerste waarschuwing aan onze reizigers en zakelijke partners moesten uitsturen. Dit was zelfs dagen vóór de Wereldgezondheidsorganisatie!

Tijdens de onvermijdelijke nasleep hadden we een openbaring. De ziekte verspreidde zich zo snel dat het ons duidelijk was dat de wereldwijde reactie op zijn best chaotisch zou zijn. Elk land zou zijn eigen set regels en voorschriften invoeren om de verspreiding te beheersen. Dit zou onvermijdelijk wereldwijd reizen ontwrichten en een enorme bron van verwarring zijn voor degenen die nog steeds willen reizen. We hadden gelijk en besloten er iets aan te doen. Sitata was een van de eerste bedrijven ter wereld die een speciale API en monitoringdienst creëerde voor veranderingen in reisbeperkingen en toegangseisen als gevolg van COVID-19. Met een geavanceerd softwaresysteem voor gebeurtenisdetectie en een toegewijd team van analisten hadden we al de juiste tools en processen om dit te doen.

Sinds de lancering van deze nieuwe service hebben we een verscheidenheid aan organisaties die de data benutten ten behoeve van hun eigen klanten, waaronder Eddy Travels, Flight Centre en Etihad Airways; en er volgen binnenkort meer aankondigingen! Om meer reisgerichte organisaties te helpen profiteren van dit aanbod, hebben we hieronder een reeks voorbeelden uitgebreid beschreven om uit te leggen hoe de API te gebruiken voor verschillende use cases. Ik hoop dat deze uitleg je helpt om je eigen initiatieven van de grond te krijgen.

Toegangseisen

Zonder twijfel zijn de eerste vragen die een reiziger stelt “kan ik daarheen?” en “kom ik in quarantaine?”, dus dit is een goed startpunt. We hebben de dataset Toegangseisen gemaakt om de harde “ja/nee” vragen over toegang tot een land of regio te beantwoorden.

Op het moment van schrijven bevatte deze dataset de volgende 10 afzonderlijke categorieën:

• Mag een inwoner het land binnenkomen?
• Mag een buitenlander het land binnenkomen?
• Is doorreis door het land toegestaan?
• Is een test bij aankomst vereist (uitbraak van ziekte)?
• Is een testcertificaat toegestaan (uitbraak van ziekte)?
• Is quarantaine bij aankomst vereist (uitbraak van ziekte)? Is een vaccinatie vereist?
• Is een verzekering vereist?
• Is een testcertificaat vereist?
• Is een registratieformulier vereist? (gezondheid of anders)

Elke categorie kan een van de volgende waarden hebben:

• Ja
• Ja, met uitzonderingen
• Nee
• Nee, met uitzonderingen

Hoewel de overgrote meerderheid van de waarden “ja” en “nee” is, is de situatie ter plaatse niet altijd zo eenvoudig. Soms zijn er echt vreemde en gekke regels die verschillende overheden hebben ingesteld en die de “met uitzonderingen” waarden vereisen.

Een toegangseis is in wezen een record dat een set regels documenteert die door een actor worden opgelegd aan een of meerdere landen of regio’s. De actor kan in onze data-architectuur een land, staat of zelfs gemeente zijn. Over het algemeen dekt Sitata momenteel data op landniveau. We hebben echter enkele staats-/provincierecords voor geselecteerde regio’s zoals de Verenigde Staten en andere.

Elk record dat een invoer heeft onder het veld **origin_country_division_id** of **origin_country_region_id** is respectievelijk een record op staats- of gemeenteniveau. Als je meer gedetailleerde data wilt hebben, neem dan contact met ons op en we kunnen je use case bespreken.

Neem even de tijd om vertrouwd te raken met de datastructuur van de toegangseisen door een kijkje te nemen in onze API-documentatie hier.

Een beetje verwarrend onderdeel van de datastructuur is ons gebruik van de term “origin” (oorsprong). Dit is verwarrend omdat ontwikkelaars vaak denken dat de oorsprong de plaats van herkomst of vertrek is. Wat we echter bedoelen met oorsprong is eigenlijk de bron van de regel die aan anderen wordt opgelegd, d.w.z. het land of de regio die de beperking heeft ingesteld.

Een ander belangrijk punt om op te merken is hoe onze lijst met getroffen landen werkt. Als affected_countries leeg is, moet dit worden geïnterpreteerd als een wereldwijde regel, d.w.z. alle landen zijn getroffen.

Enkele voorbeelden

Zoals je in de documentatie hebt gezien, zijn er verschillende manieren om data uit de API op te halen. Hieronder bekijken we enkele van de meest voorkomende use cases.

Hoe krijg ik de toegangseisen tussen twee landen?

Er zijn een paar manieren om dit soort verzoek te doen. De eenvoudigste versie is gebruikmaken van de parameters **destination** en **departure**. Deze parameters accepteren ISO 3166-1 alfa-2 codes als invoer.

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

De reactie omvat alle vereisten (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt vanuit het vertrekland en reist naar het bestemmingsland.

Wat als ik data op staatsniveau wil?

Sitata heeft data op staatsniveau voor bepaalde regio’s. Je weet dat een specifieke invoer voor een staat is als het veld origin_country_division_id een waarde heeft. Je kunt ook filteren om alleen data op staatsniveau op te halen met de parameter **destination_country_division**. Deze verwacht een ISO_3166-2 waarde. Bijvoorbeeld US-TX voor Texas, VS.

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

Merk op dat het eenvoudiger kan zijn om een query per land uit te voeren en vervolgens te filteren op de staatsdata om te zien of die data bestaat, en deze te gebruiken als ze bestaan.

Hoe krijg ik de toegangseisen tussen twee luchthavens?

Net als bij landen kan de Sitata API resultaten teruggeven tussen twee luchthavens. De parameters departure_airport en destination_airport gebruiken ICAO of IATA luchthavencodes om de resultaten te filteren. De reactie omvat alle beperkingen (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt vanuit het corresponderende vertrekland en reist naar het bestemmingsland.

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

De reactie omvat alle beperkingen (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt vanuit het vertrekland en reist naar het bestemmingsland.

Wat als ik alleen stadsinformatie heb?

Sitata heeft ervoor gekozen om geen queries op basis van een specifieke stadsnaam te ondersteunen, omdat dit tot conflicten en verwarring kan leiden. In plaats daarvan hebben we ervoor gekozen om queries naar onze API te ondersteunen op basis van breedte- en lengtegraadcoördinaten, wat geen dubbelzinnigheid oplevert in onze resultatenset. De parameters zijn departure_lat, departure_lng, destination_lat en 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

Als je je steden omzet naar locaties en een query doet op basis van de coördinaten, zal onze API reageren met alle beperkingen (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt vanuit het vertrekland en reist naar het bestemmingsland.

Aanvullende data

Voor sommige soorten toegangseisen kunnen er aanvullende data geassocieerd zijn in een metadata-type veld genaamd extras. Dit veld is een key/value mapping van verschillende extra stukjes informatie voor een specifieke vereiste.

Wat is het aantal quarantainedagen?

Deze data-invoer valt onder de toegangseis type 5. In deze invoer bevat de **extras** mapping een veld genaamd quarantine_days dat een geheel getal bevat voor het aantal opgelegde quarantainedagen.

Wat is het aantal uren voor binnenkomst voor een negatieve covid-test?

Deze data-invoer valt onder de toegangseis type 8. In deze invoer bevat de **extras** mapping een veld genaamd entry_hours dat een geheel getal bevat voor het aantal uren dat een negatieve covid-test is toegestaan vóór binnenkomst.

Laat het ons weten

Wij denken dat we een zeer robuuste oplossing hebben die waarschijnlijk aan al je behoeften voldoet om je reizigers te helpen begrijpen wat ze onderweg waarschijnlijk zullen tegenkomen. Als je een specifieke use case hebt die we niet behandelen, laat het ons dan weten!

Wacht… er is meer!

Dit bericht maakt deel uit van een tweedelige serie die uitlegt hoe je kunt communiceren met de Sitata API voor toegangseisen en reisbeperkingsinformatie. Tot nu toe hebben we het gehad over Toegangseisen die de harde ja/nee soorten vereisten schetsen die nodig zijn om een land of regio binnen te komen, maar we hebben het nog niet gehad over wat er binnen het land gebeurt. Het ene is weten over het binnenkomen van een land, het andere is begrijpen of het mogelijk is om door het land te reizen of de stranden te bezoeken of of er een verplichte avondklok is.

Blijf op de hoogte voor het tweede bericht dat duikt in onze dataset Reisbeperkingen. Hint - het is bijna identiek, dus je kunt altijd alvast een kijkje nemen in onze API-documentatie in de tussentijd.