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

Velen van jullie weten dit misschien niet, maar de vroege fundamenten van Sitata waren gebouwd voor 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 COVID-19 opmerkten toen het begin december 2019 werd gemeld als een ongebruikelijke cluster van longontstekingsgevallen. Op 2 januari 2020 besloot ons gezondheidsteam dat we onze eerste waarschuwing aan onze reizigers en zakelijke partners moesten uitsturen. Dit was dagen vóór zelfs 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 controleren. Dit zou onvermijdelijk een ravage aanrichten in het wereldwijde reisverkeer 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 monitoringsdienst creëerde voor de 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 alle juiste tools en processen hiervoor klaarliggen.

Sinds de lancering van deze nieuwe service hebben verschillende organisaties gebruikgemaakt van de data 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 gedetailleerd een aantal voorbeelden uitgewerkt om uit te leggen hoe je de API kunt 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 “moet ik in quarantaine?” en dus is dit een goed startpunt. We hebben de dataset Toegangseisen gemaakt om de harde “ja/nee”-vragen over het betreden van een land of regio te beantwoorden.

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

• Kan een inwoner het land betreden?
• Kan een buitenlander het land betreden?
• Is doortocht door het land toegestaan?
• Is een test vereist bij aankomst (ziekte-uitbraak)?
• Is een testcertificaat toegestaan (ziekte-uitbraak)?
• Is quarantaine vereist bij aankomst (ziekte-uitbraak)? Is vaccinatie vereist?
• Verzekering vereist?
• Testcertificaat vereist?
• Toegangsformulier 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, wat de waardetypen “met uitzonderingen” noodzakelijk maakt.

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

Elk record dat een invoer heeft onder het veld **origin_country_division_id** of **origin_country_region_id** is respectievelijk op staats- of gemeenteniveau. Als je meer gedetailleerde gegevens wilt hebben, kun je contact met ons opnemen en kunnen we praten over jouw use case.

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

Een enigszins verwarrend onderdeel van de gegevensstructuur is ons gebruik van de term “origin”. Dit is verwarrend omdat ontwikkelaars vaak denken aan origin als de plaats van herkomst of vertrek. Wat wij echter bedoelen met origin is eigenlijk de oorsprong van de regel die aan anderen wordt opgelegd. Dat wil zeggen, 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. Dat wil zeggen, alle landen worden getroffen.

Een paar voorbeelden

Zoals je misschien uit de documentatie hebt gezien, zijn er verschillende manieren om gegevens uit de API op te halen. Hieronder lopen we een paar van de meer gebruikelijke use cases door.

Hoe haal ik de eisen tussen twee landen op?

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

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

Het antwoord bevat alle vereisten (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt uit het vertrekland en reist naar het bestemmingsland.

Wat als ik gegevens op staatsniveau wil?

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

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

Merk op dat het eenvoudiger kan zijn om op land te zoeken en vervolgens te filteren op staatsgegevens om te zien of dergelijke gegevens bestaan, en deze te gebruiken als ze bestaan.

Hoe haal ik de eisen tussen twee luchthavens op?

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

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

Het antwoord bevat alle beperkingen (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt uit het vertrekland en reist naar het bestemmingsland.

Wat als ik alleen stadsinformatie heb?

Sitata heeft ervoor gekozen om geen queries op een specifieke stadsnaam te ondersteunen, omdat dit tot conflicten en verwarring kan leiden. In plaats daarvan hebben we ervoor gekozen om het opvragen van onze API op basis van breedte- en lengtegraadcoördinaten mogelijk te maken, wat geen dubbelzinnigheid in onze resultatenset oplevert. 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 op basis van coördinaten opvraagt, reageert onze API met alle beperkingen (op land- en staatsniveau) die nodig zijn om te begrijpen voor de reiziger die vertrekt uit het vertrekland en reist naar het bestemmingsland.

Extra gegevens

Voor sommige soorten Toegangseisen kunnen er extra bijbehorende gegevens zijn in een metadata-type veld genaamd extras. Dit veld is een sleutel/waarde-mapping van verschillende extra stukjes informatie voor een specifieke vereiste.

Wat is het aantal dagen quarantaine?

Deze gegevensinvoer 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 dagen opgelegde quarantaine.

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

Deze gegevensinvoer 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 toegang.

Laat het ons weten

Wij denken dat we een zeer robuuste oplossing hebben die waarschijnlijk al je behoeften dekt 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 omgaan met de Sitata API voor Toegangseisen en Reisbeperkingsinformatie. Tot nu toe hebben we het gehad over Toegangseisen, die de harde ja/nee-soort 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 is één ding om te weten of je een land binnen kunt, het is iets anders om te begrijpen of het mogelijk is om je in het land te verplaatsen, de stranden te bezoeken of of er een verplichte avondklok is.

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