Jak korzystać z API Sitata, aby określić ograniczenia podróży dla podróżnych

Wielu z was może tego nie wiedzieć, ale wczesne fundamenty Sitata zostały zbudowane pod kątem wczesnego wykrywania chorób. W rzeczywistości, nasz założyciel ma wykład TedX z 2016 roku, który w całości dotyczy dlaczego musimy ostrzegać podróżnych, aby pomóc zapobiec rozprzestrzenianiu się chorób. Nie powinno więc dziwić, że zwróciliśmy uwagę na COVID-19, gdy został zgłoszony jako nietypowe skupisko przypadków zapalenia płuc na początku grudnia 2019 roku. Do 2 stycznia 2020 roku nasz zespół ds. zdrowia ustalił, że powinniśmy wydać nasze pierwsze ostrzeżenie dla naszych podróżnych i partnerów biznesowych. Było to na kilka dni przed Światową Organizacją Zdrowia!

Podczas nieuniknionych następstw mieliśmy olśnienie. Choroba rozprzestrzeniała się tak szybko, że było dla nas jasne, że globalna reakcja będzie co najwyżej chaotyczna. Każdy kraj wprowadzi własny zestaw przepisów i zasad dotyczących kontroli rozprzestrzeniania się. To nieuchronnie spowodowałoby spustoszenie w globalnych podróżach i było ogromnym źródłem zamieszania dla tych, którzy nadal chcą podróżować. Mieliśmy rację i postanowiliśmy coś z tym zrobić. Sitata była jedną z pierwszych firm na świecie, które stworzyły dedykowane API i usługę monitorowania zmian w ograniczeniach podróży i wymogach wjazdowych w wyniku COVID-19. Dzięki zaawansowanemu systemowi oprogramowania do wykrywania zdarzeń i dedykowanemu zespołowi analityków, mieliśmy już wszystkie odpowiednie narzędzia i procesy, aby to zrobić.

Od uruchomienia tej nowej usługi wiele organizacji skorzystało z danych dla dobra swoich klientów, w tym Eddy Travels, Flight Centre i Etihad Airways; a wkrótce ogłosimy kolejne! Aby pomóc większej liczbie organizacji skupionych na podróżach skorzystać z tej oferty, szczegółowo opisaliśmy poniżej kilka przykładów, które pomogą wyjaśnić, jak korzystać z API w różnych przypadkach użycia. Mam nadzieję, że te wyjaśnienia pomogą wam uruchomić własne inicjatywy.

Wymagania wjazdowe

Bez wątpienia pierwsze pytania, jakie zadaje podróżny, to “czy mogę tam pojechać?” i “czy będę poddany kwarantannie”, więc jest to dobry punkt wyjścia. Stworzyliśmy zbiór danych Wymagania wjazdowe, aby odpowiedzieć na trudne pytania typu “tak/nie” dotyczące wjazdu do kraju lub regionu.

W chwili pisania tego tekstu zbiór danych obejmował następujące 10 odrębnych kategorii:

• Czy mieszkaniec może wjechać do kraju?
• Czy cudzoziemiec może wjechać do kraju?
• Czy tranzyt przez kraj jest dozwolony?
• Czy wymagany jest test po przyjeździe (wybuch choroby)?
• Czy zaświadczenie o wyniku testu jest dozwolone (wybuch choroby)?
• Czy wymagana jest kwarantanna po przyjeździe (wybuch choroby)? Czy wymagane jest szczepienie?
• Czy wymagane jest ubezpieczenie?
• Czy wymagane jest zaświadczenie o wyniku testu?
• Czy wymagany jest formularz wjazdowy? (zdrowotny lub inny)

Każda kategoria może mieć jedną z następujących wartości:

• Tak
• Tak, z wyjątkami
• Nie
• Nie, z wyjątkami

Chociaż zdecydowana większość wartości to “tak” i “nie”, sytuacja w terenie nie zawsze jest tak prosta. Czasami różne rządy wprowadzają naprawdę dziwne i szalone zasady, co wymusza typy wartości “z wyjątkami”.

Wymaganie wjazdowe to w istocie zapis dokumentujący zestaw reguł nałożonych przez podmiot na jeden lub wiele innych krajów lub regionów. W naszej architekturze danych podmiotem może być kraj, stan, a nawet gmina. Ogólnie rzecz biorąc, Sitata obecnie obejmuje dane na poziomie krajowym. Mamy jednak również niektóre rekordy stanowe/prowincjonalne dla wybranych regionów, takich jak Stany Zjednoczone i inne.

Każdy rekord, który ma wpis w polu **origin_country_division_id** lub **origin_country_region_id**, jest odpowiednio rekordem na poziomie stanowym lub gminnym. Jeśli chcieliby Państwo uzyskać bardziej szczegółowe dane, prosimy o kontakt, a możemy omówić Państwa przypadek użycia.

Prosimy poświęcić chwilę na zapoznanie się ze strukturą danych Wymagań wjazdowych, przeglądając naszą dokumentację API tutaj.

Nieco mylącą częścią struktury danych jest nasze użycie terminu “origin” (źródło). Jest to mylące, ponieważ często programiści myślą o źródle jako miejscu pochodzenia lub miejscu wylotu. Jednak przez źródło rozumiemy faktyczne źródło reguły nałożonej na innych, tj. kraj lub region, który stworzył ograniczenie.

Kolejnym ważnym punktem do odnotowania jest sposób działania naszej listy krajów objętych ograniczeniami (affected_countries). Jeśli lista affected_countries jest pusta, należy to interpretować jako regułę globalną, tj. wszystkie kraje są objęte ograniczeniem.

Kilka przykładów

Jak mogliście zauważyć w dokumentacji, istnieje kilka sposobów na pobranie danych z API. Poniżej omówimy kilka bardziej typowych przypadków użycia.

Jak pobrać wymagania między dwoma krajami?

Istnieje kilka sposobów na wykonanie tego typu zapytania. Najprostsza wersja to użycie parametrów **destination** (cel) i **departure** (wylot). Parametry te akceptują jako dane wejściowe kody ISO 3166-1 alpha-2.

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

Odpowiedź będzie zawierać wszystkie wymagania (na poziomie kraju i stanu) niezbędne do zrozumienia dla podróżnego wyjeżdżającego z kraju wylotu i podróżującego do kraju docelowego.

A co jeśli chcę danych na poziomie stanu?

Sitata posiada dane na poziomie stanu dla niektórych regionów. Będziesz wiedział, że dany wpis dotyczy stanu, jeśli pole origin_country_division ma wartość. Możesz również filtrować, aby pobrać tylko dane na poziomie stanu, używając parametru **destination_country_division**. Oczekuje on wartości ISO_3166-2. Na przykład, US-TX dla Teksasu, Stany Zjednoczone.

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

Należy zauważyć, że może być prostsze wykonać zapytanie według kraju, a następnie przefiltrować dane stanowe, aby sprawdzić, czy takie dane istnieją, i użyć ich, jeśli istnieją.

Jak pobrać wymagania między dwoma lotniskami?

Podobnie jak w przypadku krajów, API Sitata może zwracać wyniki między dwoma lotniskami. Parametry departure_airport (lotnisko wylotu) i destination_airport (lotnisko docelowe) używają kodów ICAO lub IATA do filtrowania wyników. Odpowiedź będzie zawierać wszystkie ograniczenia (na poziomie kraju i stanu) niezbędne do zrozumienia dla podróżnego wyjeżdżającego z odpowiedniego kraju wylotu i podróżującego do kraju docelowego.

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

Odpowiedź będzie zawierać wszystkie ograniczenia (na poziomie kraju i stanu) niezbędne do zrozumienia dla podróżnego wyjeżdżającego z kraju wylotu i podróżującego do kraju docelowego.

A co jeśli mam tylko informacje o mieście?

Sitata zdecydowała się nie obsługiwać zapytań według konkretnej nazwy miasta, ponieważ mogłoby to prowadzić do konfliktów i zamieszania. Zamiast tego zdecydowaliśmy się umożliwić odpytywanie naszego API za pomocą współrzędnych szerokości i długości geograficznej, co nie powoduje żadnej niejednoznaczności w naszym zestawie wyników. Parametry to departure_lat, departure_lng, destination_lat i 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

Jeśli rozwiążesz swoje miasta do lokalizacji i wykonasz zapytanie na podstawie współrzędnych, nasze API odpowie wszystkimi ograniczeniami (na poziomie kraju i stanu) niezbędnymi do zrozumienia dla podróżnego wyjeżdżającego z kraju wylotu i podróżującego do kraju docelowego.

Dodatkowe dane

Dla niektórych typów Wymagań wjazdowych mogą istnieć dodatkowe powiązane dane w polu typu metadane o nazwie extras. To pole jest mapowaniem klucz/wartość różnych dodatkowych informacji dla danego wymagania.

Jaka jest liczba dni kwarantanny?

Ten wpis danych podlega wymaganiu wjazdowemu typu 5. W tym wpisie mapowanie **extras** będzie zawierać pole o nazwie quarantine_days, które będzie zawierać liczbę całkowitą oznaczającą liczbę dni nałożonej kwarantanny.

Jaka jest liczba godzin przed wjazdem dla negatywnego testu na covid?

Ten wpis danych podlega wymaganiu wjazdowemu typu 8. W tym wpisie mapowanie **extras** będzie zawierać pole o nazwie entry_hours, które będzie zawierać liczbę całkowitą oznaczającą liczbę godzin, przez które negatywny test na covid jest ważny przed wjazdem.

Daj nam znać

Uważamy, że mamy bardzo solidne rozwiązanie, które prawdopodobnie zaspokoi wszystkie wasze potrzeby, aby pomóc waszym podróżnym zrozumieć, co prawdopodobnie napotkają po drodze. Jeśli macie konkretny przypadek użycia, którego nie uwzględniamy, prosimy dać nam znać!

Czekaj… to nie wszystko!

Ten wpis jest częścią dwuczęściowej serii, która wyjaśnia, jak korzystać z API Sitata w celu uzyskania informacji o Wymaganiach wjazdowych i Ograniczeniach podróży. Do tej pory mówiliśmy o Wymaganiach wjazdowych, które określają twarde wymagania typu tak/nie niezbędne do wjazdu do kraju lub regionu, ale nie mówiliśmy jeszcze o tym, co dzieje się wewnątrz kraju. Jedną rzeczą jest wiedzieć o wjeździe do kraju, a inną zrozumieć, czy można się po nim przemieszczać, odwiedzać plaże lub czy obowiązuje obowiązkowa godzina policyjna.

Wyczekujcie drugiego posta, który zagłębi się w nasz zbiór danych Ograniczeń podróży. Podpowiedź - jest on niemal identyczny, więc w międzyczasie zawsze możecie rzucić okiem na naszą dokumentację API.