#Trips

Personalized travel restrictions for every journey.

#Introduction

The Trips endpoint lets developers retrieve personalized travel restrictions and documents based on trip context like origin, destination, and date of travel.

#Definitions

#ISO 3166-1 Territory

ISO 3166-1 is a standard defining a code for the names of countries, dependent territories, and special areas of geographical interest. We will use this terminology throughout this document instead of countries and territories. At sherpa°, we default to ISO 3166-1 alpha-3 unless stated otherwise.

#Transit/Connection

When the customer’s ticket between two locations includes one or more locations in between where travellers have to disembark the airplane and board another one. The customer will not be leaving the airport in this scenario.

#Self Transit or Virtual Interlining

A technology used by travel companies that combines flights from different carriers that don't traditionally work together to go from point A to B via C. Travellers might also create their custom trip by booking separate tickets simultaneously to reach their final destination. The customer may leave the airport in this scenario to fly out from another airport in the same city.

#Multi-Connection trip

If a trip between an origin and destination has at least one connection or transit, excluding self transit or virtual interlining.

#Multi-Segment trip

A trip that has multiple flights, and the traveller is able to leave the airport at each transit point, even if they stay inside the airport. All trips with self-transit or virtual interlining are multi-connection trips.

#Domestic Flight

A flight between two points where the origin and destination and transit points are located in the same ISO 3166-1 Territory. For example, Toronto to Vancouver, New York to Los Angeles, Edmonton to Calgary, etc.

#International Flight

A flight between two points where the origin and destination [or transit points] are located in a different ISO 3166-1 Territory. For example, London to Paris (the U.K. and France), New York to Tokyo (USA and Japan), etc.

All international travel requirements that apply will be shown on these trips.

#International Transit

This is an international flight between two points where passengers are not formally entering the destination ISO 3166-1 Territory, but only transiting through on their way to a final destination.

For example, if one is flying from Toronto to Dubai with a layover in London, Toronto to London would be considered an international transit. International transit requirements will apply from Toronto to London and international flight requirements will apply from London to Dubai.

#Request Headers

Each call to the API must include your unique API key and the content type as headers. Additional optional headers are listed in the table below.

#Describing a Trip

A trip can be described with a type and an attribute object containing the trip details.

#Attributes Object

The attributes object contains all the details relevant to the trip. This includes information about the traveller, origin, destination, and localization attributes such as language and currency.

#Describing a Traveller

A Traveller object is used to describe the specific travellers taking part in a trip. A traveller is an individual (PAX) person.

#Describing a Travel Node

A travel node is either an origin or destination and contains all of the related itinerary details. The table below defines the properties related to this object.

#Describing an arrival or departure object

curl --location --request POST 'https://requirements-api.sandbox.joinsherpa.com/v3/trips' \
--header 'Content-Type: application/vnd.api+json' \
--header 'x-api-key: YOUR_API_KEY' \
--data-raw '{
    "data": {
        "type": "TRIP",
        "attributes": {
            "locale": "en-US",
            "traveller": {
                "passports": ["USA"]
            },
            "currency": "USD",
            "travelNodes": [
                {
                    "type": "ORIGIN",
                    "locationCode": "USA",
                    "departure": {
                        "date": "2022-12-01",
                        "time": "12:59",
                        "travelMode": "AIR"
                    }
                },
                {
                    "type": "DESTINATION",
                    "locationCode": "TUR",
                    "arrival": {
                        "date": "2022-12-01",
                        "time": "22:59",
                        "travelMode": "AIR",
                        "flightNumber": "AB1234"
                    }
                }
            ]
        }
    }
}'

#Unsupported Cases

Even though a trip might be valid syntax, it might not provide the desired output. Here are some cases we currently don't support along with a brief description and example

Airport -> Airport (within same region) Example: SFO -> SAN Travel rules remain the same within the same region.

"alerts": [
  "We don't have information for travel within California. Be sure to check official sources."
]

Airport → Airport (Within same country but different regions with no domestic info) Example: SXF → FRA We currently only fully support regions from selected countries.

"headline": "We don't have information for travel from Berlin (SXF) to Frankfurt (FRA). Be sure to check official sources."

Airport → Region (Within same country but different regions with no domestic info) Example: COK → IN-DL

"headline": "We don't have information for travel from Kochi (COK) to Delhi. Be sure to check official sources.",

Example: SXF → DE-HE

"headline": "We don't have information for travel from Berlin (SXF) to Germany. Be sure to check official sources."

Region → Airport (Within same country but different regions with no domestic info) Example: DE-HE → SXF

"headline": "We don't have information for travel from Berlin (SXF) to Germany. Be sure to check official sources."

Region → Region (Within same country but different regions with no domestic info) Example: DE-HE → DE-BR

"headline": "We don't have information for travel within Germany. Be sure to check official sources."

Examples of invalid trips

Country -> Country (same country) Example: CAN -> CAN

Country -> Region (region in same country) Region -> Country (region in same country) Example: CA-ON -> CAN

Country -> Airport (airport in same country) Airport -> Country (airport in same country) Example: YYZ -> CAN

#Visa Specific Data on Trips Endpoint

Visa requirements show the destination country's visa (paper and eVisa) requirements for a traveller. The Visa requirements section can be found as part of the /v3/trips response or as a stand-alone request for entry requirements under the /v2/procedures resource endpoint.

Looking at a /v3/trips response, the visa requirements are listed under the attributes informationGroups with the type: VISA_REQUIREMENTS (data.attributes.informationGroups[x].type)

For a typical trip going one way from Canada(CAN) to Italy(ITA), a snippet below shows what to expect. The informationGroups section has a list of the response ids which point to details about each visa requirement necessary for the trip.

"informationGroups": [
  {
      "name": "Visa Requirements",
      "type": "VISA_REQUIREMENTS",
      "tooltip": "Visa requirements are determined by the passport you are travelling with and duration of your trip.",
      "groupings": [
          {
              "name": "Italy",
              "enforcement": "NOT_REQUIRED",
              "data": [
                  {
                      "type": "PROCEDURE",
                      "id": "9e170760-a9cc-446b-9389-4be9f4e29022"
                  }
              ]
          }
      ],
      "enforcement": "NOT_REQUIRED",
      "headline": "You don't need a visa for Italy if you have a Canadian passport."
  }]

A search of the id "9e170760-a9cc-446b-9389-4be9f4e29022" takes us to the included[0] section of the trip response, where details of the visa requirement are listed below.

 "included": [
    {
      "id": "9e170760-a9cc-446b-9389-4be9f4e29022",
      "type": "PROCEDURE",
      "attributes": {
        "category": "DOC_REQUIREMENT",
        "subCategory": "BEFORE_ARRIVAL",
        "title": "Visa is not required ",
        "description": "Travelers don’t need a visa to visit Italy for Business or Tourism.",
        "more": [],
        "actions": [],
        "sources": [
          {
            "type": "GOVERNMENT",
            "title": "Ministry of Foreign Affairs of Italy",
            "url": "https://vistoperitalia.esteri.it/home/en"
          }
        ],
        "lastUpdatedAt": "2022-10-07T08:04:00.000Z",
        "createdAt": "2021-04-27T03:44:00.000Z",
        "startDate": null,
        "endDate": null,
        "enforcement": "NOT_REQUIRED",
        "documentTypes": [
          "VISA"
        ],
        "tags": [
          "international",
          "fully_vaccinated",
          "not_vaccinated",
          "land",
          "air",
          "sea",
          "tourism",
          "business"
        ],
        "travelPurposes": [
          "TOURISM",
          "BUSINESS"
        ],
        "lengthOfStay": [
          {
            "type": "DAYS",
            "value": 90,
            "text": "90 days"
          }
        ],
        "included": [
          {
            "code": "ALB",
            "text": "Albania (ALB)",
            "type": "PASSPORT"
          },
          ...
          {
            "code": "DEU",
            "text": "Germany (D)",
            "type": "PASSPORT"
          },
          {
            "code": "GRC",
            "text": "Greece (GRC)",
            "type": "PASSPORT"
          },
          ...
          {
            "code": "VEN",
            "text": "Venezuela (VEN)",
            "type": "PASSPORT"
          }
        ],
        "icon": {
          "name": "visa"
        }
      },
      "relationships": {
        "location": {
          "data": {
            "id": "ITA",
            "type": "LOCATION"
          }
        }
      }
    }

The visa requirement contains the following attributes as explained in the tables below: