Jak korzystać z API Sitata do określania ograniczeń podróży dla podróżujących

Wielu z was może nie wiedzieć, ale pierwsze fundamenty Sitata zostały zbudowane pod kątem wczesnego wykrywania chorób. W rzeczy samej, nasz założyciel ma nawet prelekcję TedX z 2016 roku o tym, dlaczego musimy ostrzegać podróżnych, aby pomóc w zapobieganiu rozprzestrzenianiu się chorób. Nie powinno więc dziwić, że dowiedzieliśmy się o COVID-19, gdy na początku grudnia 2019 roku zgłoszono nietypowe skupisko przypadków zapalenia płuc. 2 stycznia 2020 roku nasz zespół ds. zdrowia uznał, że musimy wydać nasze pierwsze ostrzeżenie dla naszych podróżnych i partnerów biznesowych. Było to na kilka dni przed nawet Ś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 w najlepszym razie chaotyczna. Każdy kraj wprowadzi własny zestaw przepisów i zasad mających na celu kontrolę rozprzestrzeniania się. To nieuchronnie spowodowałoby chaos w światowych podróżach i byłoby 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óra stworzyła dedykowane API i usługę monitorowania zmian w ograniczeniach podróży i wymogach wjazdowych wynikających z 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 tych danych na korzyść swoich własnych 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 serię 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ą Ci uruchomić własne inicjatywy.

Wymagania wjazdowe

Zdecydowanie pierwszymi pytaniami, jakie zadaje podróżny, są “czy mogę tam pojechać?” i “czy zostanę poddany kwarantannie?”, więc jest to dobry punkt wyjścia. Stworzyliśmy zbiór danych Wymagań Wjazdowych, aby odpowiedzieć na twarde “tak/nie” na pytania dotyczące wjazdu do kraju lub regionu.

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

• Czy rezydent 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 rejestracyjny? (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 istnieją naprawdę dziwne i szalone zasady, które wprowadziły różne rządy, wymagające wartości typu “z wyjątkami”.

Wymóg wjazdowy to w istocie rekord dokumentujący zestaw zasad narzuconych przez podmiot wobec jednego lub wielu krajów lub regionów. Podmiotem w naszej architekturze danych może być kraj, stan, a nawet gmina. Ogólnie rzecz biorąc, Sitata obecnie obejmuje danymi poziom krajowy. Mamy jednak kilka rekordów stanowych/prowincjonalnych 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 potrzebujesz bardziej szczegółowych danych, skontaktuj się z nami, a możemy omówić Twój przypadek użycia.

Prosimy poświęcić chwilę na zapoznanie się ze strukturą danych Wymagań Wjazdowych, spoglądając na 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ż programiści często myślą, że źródło to miejsce pochodzenia lub wyjazdu. Jednak przez źródło mamy na myśli tak naprawdę źródło reguły narzuconej innym, czyli 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. Jeśli affected_countries jest puste, należy to interpretować jako regułę globalną, tj. wszystkie kraje są objęte.

Kilka przykładów

Jak zapewne widzieliście w dokumentacji, istnieje kilka sposobów na pobranie danych z API. Przyjrzymy się teraz kilku najczęstszym przypadkom użycia.

Jak uzyskać wymagania między dwoma krajami?

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

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 wyjazdu i podróżującego do kraju docelowego.

A co, jeśli chcę danych na poziomie stanowym?

Sitata posiada dane na poziomie stanowym dla niektórych regionów. Będziesz wiedział, że dany wpis dotyczy stanu, jeśli pole origin_country_division_id 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 w USA.

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

Zauważ, że może być prostsze wykonać zapytanie o kraj, a następnie przefiltrować dane stanowe, aby sprawdzić, czy istnieją, i użyć ich, jeśli tak.

Jak uzyskać wymagania między dwoma lotniskami?

Podobnie jak w przypadku krajów, API Sitata może zwracać wyniki między dwoma lotniskami. Parametry departure_airport i destination_airport 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 wyjazdu 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 wyjazdu i podróżującego do kraju docelowego.

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

Sitata postanowiła nie obsługiwać zapytań o konkretną nazwę miasta, ponieważ mogłoby to prowadzić do konfliktów i zamieszania. Zamiast tego zdecydowaliśmy się obsługiwać zapytania do naszego API za pomocą współrzędnych szerokości i długości geograficznej, co nie wprowadza żadnej niejednoznaczności do naszego zestawu 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 zlokalizujesz swoje miasta 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 wyjazdu i podróżującego do kraju docelowego.

Dodatkowe dane

Dla niektórych typów wymagań wjazdowych mogą istnieć dodatkowe dane powiązane w polu metadanych typu extras. To pole to mapa 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ć

Wierzymy, że mamy bardzo solidne API, które prawdopodobnie zaspokoi wszystkie Twoje potrzeby związane z pomocą podróżnym w zrozumieniu tego, co prawdopodobnie napotkają po drodze. Jeśli masz konkretny przypadek użycia, którego nie uwzględniamy, prosimy, daj nam znać!

Czekaj… to nie wszystko!

Ten wpis jest częścią dwuczęściowej serii wyjaśniającej, jak korzystać z API Sitata w zakresie wymagań wjazdowych i informacji o ograniczeniach podróży. Do tej pory mówiliśmy o Wymaganiach Wjazdowych, które opisują twarde wymagania typu tak/nie niezbędne do wjazdu do kraju lub regionu, ale nie poruszyliśmy jeszcze tego, co dzieje się wewnątrz kraju. Jedna rzecz to wiedzieć o wjeździe do kraju, a inna to zrozumieć, czy można się po nim przemieszczać, czy odwiedzać plaże, czy też obowiązuje obowiązkowa godzina policyjna.

Zostańcie z nami na drugi post, który zagłębi się w nasz zbiór danych Ograniczeń Podróży. Podpowiedź - jest prawie identyczny, więc zawsze możesz w międzyczasie rzucić okiem na naszą dokumentację API.