Sherpa - Visa and Travel Restrictions API

Sherpa Developer Hub

Welcome to the Sherpa developer hub. We offer a suite of solutions that guides travellers from planning to a safe return home. Take a look at the integration guides, specific use cases and an interactive API Reference. Ready? Let's go.

Guides    API Reference

πŸ›« Trip

Display travel restrictions for a trip.

Travel restrictions for a Trip LegTrip Leg - A leg of a journey is the part of an air route or a flight pattern that is between two successive stops, positions, or changes in direction.

Visa requirements are based on a traveller's nationality and destination. Travel restrictions and procedures introduced as as result of COVID-19 are often based on your point of origin, recent travel history and date of travel.

Our plug & play widget allows you to display this information alongside entry requirements, providing a single point of reference for your travellers. The results take the traveller's departure date into context, meaning that if there's a planned change between booking & travel they'll be aware.

Query Travel Restrictions for Trip LegTrip Leg - A leg of a journey is the part of an air route or a flight pattern that is between two successive stops, positions, or changes in direction. using the API

The Travel Restrictions API offers a series of restrictions and procedures that are currently active on a country or regional (administrate division such as "state") level. In order to provide more context and limit the results returned, filters for origin and destination as well as active date can be utilized.

To find relevant travel restrictions, we will:

  1. Query and filter outbound restrictions
  2. Query and filter inbound restrictions
  3. Determine if travel restrictions apply to this LegLeg - A leg of a journey is the part of an air route or a flight pattern that is between two successive stops, positions, or changes in direction. .

Let's look at a Trip LegTrip Leg - A leg of a journey is the part of an air route or a flight pattern that is between two successive stops, positions, or changes in direction. of Australia to the United States.

1. Query Outbound Travel Restrictions

https://requirements-api.sandbox.joinsherpa.com/v2/countries/AUS?key={apiKey}
&include=restriction,procedure
&filter[restriction.destinationCountries]=USA
&filter[procedure.destinationCountries]=USA
&filter[restriction.activeDate]=2020-09-28
&filter[procedure.activeDate]=2020-09-28

In the example, we are requesting all restrictions and procedures and including these in our response via (&include=restriction,procedure) that are active for the departing (origin) country Australia.
We set the activeDate for both, restrictions and procedures as our date of travel will be on September, 28th of 2020.
To show only relevant restrictions and procedures when leaving Australia, we need to provide the API with that information to filter out restrictions and procedures that otherwise apply for different countries. Therefore we set the destinationCountries to United States.

The response will include several restrictions and procedures that we can filter by category and subCategory in order to provide a more helpful message on the frontend.

Restrictions can be filtered, to only include those categories relevant to the departure:

Categories

  • RESTRICTED_EXIT
  • NO_EXIT

Sub-categories

  • EXIT
  • DOMESTIC (e.g. if domestic travel is relevant)

Procedures can be filtered, to only include following categories relevant to the departure:
Sub-categories

  • IN_AIRPORT
const key = '{apiKey}';
const sherpaApiUrl = 'https://requirements-api.sandbox.joinsherpa.com/v2';

const origin = 'AUS';
const destination = 'USA';
const travelDate = '2020-09-28';

// Outbound
(async () => {

const url = `${sherpaApiUrl}/countries/${origin}?key=${key}&filter[restriction.destinationCountries]=${destination}&filter[procedure.destinationCountries]=${destination}&filter[procedure.activeDate]=${travelDate}&filter[restriction.activeDate]=${travelDate}&include=restriction,procedure`;

  let restrictionsAndProcedures = await fetch(url).then(response => response.json()).then(response => response.included);

  restrictionsAndProcedures = restrictionsAndProcedures.filter(r => {
    if (r.type === 'PROCEDURE') {
      return r.attributes.subCategory === 'IN_AIRPORT'
    }

    if (r.type === 'RESTRICTION') {
      return r.attributes.category === 'RESTRICTED_EXIT' || //
        r.attributes.category === 'NO_EXIT' || //
        r.attributes.subCategory === 'EXIT' || //
        r.attributes.subCategory === 'DOMESTIC'
    }
  })

})()

🚧

Categories and Sub-Categories may be updated

Restrictions and procedures are continuously changing. The Plug & Play Widget is updated on a regular basis as categories are modified or being added. If you are using our API directly, please subscribe to the Changelog to stay updated.

2. Query Inbound Travel Restrictions

https://requirements-api.joinsherpa.com/v2/countries/USA?key={apiKey}
&filter[restriction.originCountries]=AUS
&filter[procedure.originCountries]=AUS
&filter[procedure.activeDate]=2020-09-28
&filter[restriction.activeDate]=2020-09-28
&include=restriction,procedure

Based on our example, we're now reversing our request to retrieve all restrictions and procedures that apply to the United States. In addition to ensuring we include restrictions and procedures in our response by providing the include=restriction,procedure query param, we also filter by originCountries. Similar to the previous example, we apply the activeDate filter to ensure restrictions and procedures are in effect of the travel date.

The response will include several restrictions and procedures that we can filter by category and subCategory in order to provide a more helpful message on the frontend, this time for the arrival to the United States.

Restrictions can be filtered, to only include those categories relevant to the arrival:

Categories

  • NO_ENTRY
  • ENTRY
  • RESTRICTED_ENTRY
  • DOMESTIC (e.g. if domestic travel is relevant)

Sub-categories

  • ON_ARRIVAL

Procedures can be filtered, but in most scenarios all procedures are relevant.

const key = '{apiKey}';
const sherpaApiUrl = 'https://requirements-api.sandbox.joinsherpa.com/v2';

const origin = 'AUS';
const destination = 'USA';
const travelDate = '2020-09-28';

// Inbound
(async () => {

  const url = `${sherpaApiUrl}/countries/${destination}?key=${key}&filter[restriction.originCountries]=${origin}&filter[procedure.originCountries]=${origin}&filter[procedure.activeDate]=${travelDate}&filter[restriction.activeDate]=${travelDate}&include=restriction,procedure`;

  let restrictionsAndProcedures = await fetch(url).then(response => response.json()).then(response => response.included);

  restrictionsAndProcedures = restrictionsAndProcedures.filter(r => {
    if (r.type === 'PROCEDURE') {
      return r.attributes.subCategory === 'IN_AIRPORT'
    }

    if (r.type === 'RESTRICTION') {
      return r.attributes.category === 'NO_ENTRY' || //
        r.attributes.category === 'ENTRY' || //
        r.attributes.category === 'RESTRICTED_ENTRY' || //
        r.attributes.subCategory === 'DOMESTIC'
      r.attributes.subCategory === 'ON_ARRIVAL' || //
    }
  })

})()

The results from both API requests can then be combined to be displayed to a user.

3. Determine if travel restrictions apply to this LegLeg - A leg of a journey is the part of an air route or a flight pattern that is between two successive stops, positions, or changes in direction. .

Looking at remaining travel restrictions and procedures, we can provide helpful messages to the user.

Do I have to quarantine?

If a procedure with category QUARANTINE remained, you can display a message There are quarantine restrictions for your trip. and provide your users with a way to look at the details.

Are there any restrictions for my trip ?

If a restriction with category NO_ENTRY, RESTRICTED_ENTRY or ENTRY remained, you can display a message There are travel restrictions for your trip.

If both Quarantine procedures and entry restrictions remain, we recommend to use the wording Most travellers can't not allowed to travel to X . Often the restrictions contain exceptions to allow citizens and residents to return back home.

πŸ“˜

Utilizing localized Title and Description

Each restriction and procedure has a short but descriptive title and a concise description which is intended to be displayed to the end user. These fields are also localized and we recommend to use these fields as they can contain relevant details.

Updated 4 months ago


πŸ›« Trip


Display travel restrictions for a trip.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.