Trips [v2]
Personalized travel restrictions for every journey.
Deprecated
This page is for v2 of the Trips endpoint and is out of date. For the current version, click here.
Introduction
The Trips endpoint lets developers retrieve personalized travel restrictions and documents based on trip context like origin, destination, date of travel.
Note
Trips endpoint is a convenient way to retrieve contextualized Restrictions and Procedures enforced by Countries or Regions.
Describing a Trip
A Trip can be described using one or multiple Segment.
| Property | Type | Description |
|---|---|---|
| category | string | ONE_WAY_TRIP, ROUND_TRIP |
| segments | Array of Segments | Segments describing the trip |
| travellers | Array of Travellers | Travellers taking part in the trip |
Describing a Segment
A Segment is used to describe the specific part of the trip like a flight or bus ride from one city to the next.
| Property | Type | Description |
|---|---|---|
| segmentType | string | RETURN or OUTBOUND |
| origin.countryCode | string | ISO3 Country Code |
| destination.countryCode | string | ISO3 Country Code |
| departureDate | string | A departure date YYYY-MM-DD |
| departureTime | string | HH:MM |
| arrivalDate | string | Arrival date YYYY-MM-DD |
| arrivalTime | string | HH:MM |
curl --location --request POST 'https://requirements-api.sandbox.joinsherpa.com/v2/trips?affiliateId=sherpa&key=<API_KEY>&language=en-US&include=restriction,procedure' \
--header 'x-sherpa-deviceId: sherpa-test' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"type": "TRIP",
"attributes": {
"category": "ROUND_TRIP",
"travellers": [
{
"vaccinations": [
{
"type": "COVID_19",
"status": "FULLY_VACCINATED"
}
],
"nationality": "CAN"
}
],
"segments": [
{
"segmentType": "OUTBOUND",
"origin": {
"countryCode": "CAN"
},
"destination": {
"countryCode": "GBR"
},
"travelMode": "AIR",
"departureDate": "2022-07-01",
"departureTime": "12:59",
"arrivalDate": "2022-07-02",
"arrivalTime": "12:59"
},
{
"segmentType": "RETURN",
"origin": {
"countryCode": "GBR"
},
"destination": {
"countryCode": "CAN"
},
"travelMode": "AIR",
"departureDate": "2022-07-07",
"departureTime": "12:59",
"arrivalDate": "2022-07-08",
"arrivalTime": "12:59"
}
]
}
}
}'
{
"meta": {
"copyright": "Sherpa",
"version": "2.8.3"
},
"data": {
"id": "1f5e0258-ceae-4086-a668-88d36cd68fc2",
"type": "TRIP",
"attributes": {
"category": "ROUND_TRIP",
"segments": [
{
"segmentType": "OUTBOUND",
"origin": {
"countryCode": "CAN",
"countryName": "Canada"
},
"destination": {
"countryCode": "GBR",
"countryName": "United Kingdom"
},
"travelMode": "AIR",
"departureDate": "2022-07-01T00:00:00.000Z",
"departureTime": "12:59",
"arrivalDate": "2022-07-02T00:00:00.000Z",
"arrivalTime": "12:59",
"borderCrossing": "INTERNATIONAL",
"summary": {
"headline": "Most travelers from Canada with proof of full COVID-19 vaccination can enter United Kingdom, but there are restrictions.",
"travelOpenness": "LEVEL_1",
"groupings": [
{
"type": "ORIGIN_TRAVEL_RESTRICTIONS",
"label": "MANDATORY_ORIGIN_TRAVEL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "ORIGIN_DOCUMENTS",
"label": "MANDATORY_ORIGIN_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "113de2c3-7fad-41be-b17e-0b8d0932bbdf"
}
]
},
{
"type": "DESTINATION_TRAVEL_RESTRICTIONS",
"label": "NOT_REQUIRED_DESTINATION_TRAVEL_RESTRICTIONS",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "65c809bb-019d-41d1-9f06-891fa0aec5a2"
},
{
"id": "4c291c68-c737-4959-a0b2-a7ab75cc8129"
},
{
"id": "b785ccba-d09f-4a09-bf81-c8c9f80d6fc8"
}
]
},
{
"type": "DESTINATION_DOCUMENTS",
"label": "MANDATORY_DESTINATION_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "2e2e2c51-1ac6-492a-af16-3633a4bf7fb5"
},
{
"id": "c29de12b-0269-4247-a155-2f8869512e21"
}
]
},
{
"type": "LOCAL_RESTRICTIONS",
"label": "RECOMMENDED_LOCAL_RESTRICTIONS",
"enforcement": "RECOMMENDED",
"included": [
{
"id": "5cf0e671-7c34-411c-996b-ba3376db6e3c"
}
]
},
{
"type": "UPCOMING",
"label": "MANDATORY_UPCOMING",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "VISAS",
"label": "No visa required",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "d56c7193-5200-4853-ac05-fe5a7e023dca"
}
]
}
]
}
},
{
"segmentType": "RETURN",
"origin": {
"countryCode": "GBR",
"countryName": "United Kingdom"
},
"destination": {
"countryCode": "CAN",
"countryName": "Canada"
},
"travelMode": "AIR",
"departureDate": "2022-07-07T00:00:00.000Z",
"departureTime": "12:59",
"arrivalDate": "2022-07-08T00:00:00.000Z",
"arrivalTime": "12:59",
"borderCrossing": "INTERNATIONAL",
"summary": {
"headline": "Most travelers with proof of full COVID-19 vaccination can return to Canada from United Kingdom, but there are restrictions.",
"travelOpenness": "LEVEL_2",
"groupings": [
{
"type": "ORIGIN_TRAVEL_RESTRICTIONS",
"label": "MANDATORY_ORIGIN_TRAVEL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "ORIGIN_DOCUMENTS",
"label": "MANDATORY_ORIGIN_DOCUMENTS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "DESTINATION_TRAVEL_RESTRICTIONS",
"label": "MAY_BE_REQUIRED_DESTINATION_TRAVEL_RESTRICTIONS",
"enforcement": "MAY_BE_REQUIRED",
"included": [
{
"id": "e09d1ff6-e22e-47b4-bea9-14b0bf3faf6c"
},
{
"id": "4b76c85f-871b-4288-ab5c-361ff74e6bb9"
},
{
"id": "bf49195e-7698-4f4e-90d0-1caa3a4fe08c"
}
]
},
{
"type": "DESTINATION_DOCUMENTS",
"label": "MANDATORY_DESTINATION_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "93a65c42-baca-43db-bc1f-e97ded5a6b63"
},
{
"id": "5205aa9a-7ae5-4659-8120-006e2fe8a48d"
},
{
"id": "d0a42122-094e-4c93-a70c-fcadc21ce2ce"
}
]
},
{
"type": "LOCAL_RESTRICTIONS",
"label": "MANDATORY_LOCAL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": [
{
"id": "82c335f5-eb9e-48f6-916b-52f8a3c85a13"
}
]
},
{
"type": "UPCOMING",
"label": "MANDATORY_UPCOMING",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "VISAS",
"label": "No visa required",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "generated-procedure-notRequired-visa-CAN"
}
]
}
]
}
}
],
"summary": [
{
"type": "COVID_19_TEST",
"headline": "COVID-19 test is required for one or multiple parts of your trip. View detailed information below.",
"enforcement": "MANDATORY"
},
{
"type": "QUARANTINE",
"headline": "No Quarantine",
"enforcement": "NOT_REQUIRED"
},
{
"type": "DOC_REQUIRED",
"headline": "Documents are required for one or multiple parts of your trip. View detailed information below.",
"enforcement": "MANDATORY"
},
{
"type": "VISA",
"headline": "No visa required",
"enforcement": "NOT_REQUIRED"
}
],
"outbound": {
"segmentType": "OUTBOUND",
"origin": {
"countryCode": "CAN",
"countryName": "Canada"
},
"destination": {
"countryCode": "GBR",
"countryName": "United Kingdom"
},
"travelMode": "AIR",
"departureDate": "2022-07-01T00:00:00.000Z",
"departureTime": "12:59",
"arrivalDate": "2022-07-02T00:00:00.000Z",
"arrivalTime": "12:59",
"borderCrossing": "INTERNATIONAL",
"summary": {
"headline": "Most travelers from Canada with proof of full COVID-19 vaccination can enter United Kingdom, but there are restrictions.",
"travelOpenness": "LEVEL_1",
"groupings": [
{
"type": "ORIGIN_TRAVEL_RESTRICTIONS",
"label": "MANDATORY_ORIGIN_TRAVEL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "ORIGIN_DOCUMENTS",
"label": "MANDATORY_ORIGIN_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "113de2c3-7fad-41be-b17e-0b8d0932bbdf"
}
]
},
{
"type": "DESTINATION_TRAVEL_RESTRICTIONS",
"label": "NOT_REQUIRED_DESTINATION_TRAVEL_RESTRICTIONS",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "65c809bb-019d-41d1-9f06-891fa0aec5a2"
},
{
"id": "4c291c68-c737-4959-a0b2-a7ab75cc8129"
},
{
"id": "b785ccba-d09f-4a09-bf81-c8c9f80d6fc8"
}
]
},
{
"type": "DESTINATION_DOCUMENTS",
"label": "MANDATORY_DESTINATION_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "2e2e2c51-1ac6-492a-af16-3633a4bf7fb5"
},
{
"id": "c29de12b-0269-4247-a155-2f8869512e21"
}
]
},
{
"type": "LOCAL_RESTRICTIONS",
"label": "RECOMMENDED_LOCAL_RESTRICTIONS",
"enforcement": "RECOMMENDED",
"included": [
{
"id": "5cf0e671-7c34-411c-996b-ba3376db6e3c"
}
]
},
{
"type": "UPCOMING",
"label": "MANDATORY_UPCOMING",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "VISAS",
"label": "No visa required",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "d56c7193-5200-4853-ac05-fe5a7e023dca"
}
]
}
]
},
"segmentSubType": "CONTEXT"
},
"return": {
"segmentType": "RETURN",
"origin": {
"countryCode": "GBR",
"countryName": "United Kingdom"
},
"destination": {
"countryCode": "CAN",
"countryName": "Canada"
},
"travelMode": "AIR",
"departureDate": "2022-07-07T00:00:00.000Z",
"departureTime": "12:59",
"arrivalDate": "2022-07-08T00:00:00.000Z",
"arrivalTime": "12:59",
"borderCrossing": "INTERNATIONAL",
"summary": {
"headline": "Most travelers with proof of full COVID-19 vaccination can return to Canada from United Kingdom, but there are restrictions.",
"travelOpenness": "LEVEL_2",
"groupings": [
{
"type": "ORIGIN_TRAVEL_RESTRICTIONS",
"label": "MANDATORY_ORIGIN_TRAVEL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "ORIGIN_DOCUMENTS",
"label": "MANDATORY_ORIGIN_DOCUMENTS",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "DESTINATION_TRAVEL_RESTRICTIONS",
"label": "MAY_BE_REQUIRED_DESTINATION_TRAVEL_RESTRICTIONS",
"enforcement": "MAY_BE_REQUIRED",
"included": [
{
"id": "e09d1ff6-e22e-47b4-bea9-14b0bf3faf6c"
},
{
"id": "4b76c85f-871b-4288-ab5c-361ff74e6bb9"
},
{
"id": "bf49195e-7698-4f4e-90d0-1caa3a4fe08c"
}
]
},
{
"type": "DESTINATION_DOCUMENTS",
"label": "MANDATORY_DESTINATION_DOCUMENTS",
"enforcement": "MANDATORY",
"included": [
{
"id": "93a65c42-baca-43db-bc1f-e97ded5a6b63"
},
{
"id": "5205aa9a-7ae5-4659-8120-006e2fe8a48d"
},
{
"id": "d0a42122-094e-4c93-a70c-fcadc21ce2ce"
}
]
},
{
"type": "LOCAL_RESTRICTIONS",
"label": "MANDATORY_LOCAL_RESTRICTIONS",
"enforcement": "MANDATORY",
"included": [
{
"id": "82c335f5-eb9e-48f6-916b-52f8a3c85a13"
}
]
},
{
"type": "UPCOMING",
"label": "MANDATORY_UPCOMING",
"enforcement": "MANDATORY",
"included": []
},
{
"type": "VISAS",
"label": "No visa required",
"enforcement": "NOT_REQUIRED",
"included": [
{
"id": "generated-procedure-notRequired-visa-CAN"
}
]
}
]
},
"segmentSubType": "CONTEXT"
}
},
"relationships": {
"restrictions": {
"meta": {
"count": 2
},
"data": [
{
"id": "65c809bb-019d-41d1-9f06-891fa0aec5a2",
"type": "RESTRICTION"
},
{
"id": "e09d1ff6-e22e-47b4-bea9-14b0bf3faf6c",
"type": "RESTRICTION"
}
]
},
"procedures": {
"meta": {
"count": 14
},
"data": [
{
"id": "4c291c68-c737-4959-a0b2-a7ab75cc8129",
"type": "PROCEDURE"
},
{
"id": "b785ccba-d09f-4a09-bf81-c8c9f80d6fc8",
"type": "PROCEDURE"
},
{
"id": "2e2e2c51-1ac6-492a-af16-3633a4bf7fb5",
"type": "PROCEDURE"
},
{
"id": "c29de12b-0269-4247-a155-2f8869512e21",
"type": "PROCEDURE"
},
{
"id": "5cf0e671-7c34-411c-996b-ba3376db6e3c",
"type": "PROCEDURE"
},
{
"id": "d56c7193-5200-4853-ac05-fe5a7e023dca",
"type": "PROCEDURE"
},
{
"id": "113de2c3-7fad-41be-b17e-0b8d0932bbdf",
"type": "PROCEDURE"
},
{
"id": "4b76c85f-871b-4288-ab5c-361ff74e6bb9",
"type": "PROCEDURE"
},
{
"id": "bf49195e-7698-4f4e-90d0-1caa3a4fe08c",
"type": "PROCEDURE"
},
{
"id": "5205aa9a-7ae5-4659-8120-006e2fe8a48d",
"type": "PROCEDURE"
},
{
"id": "93a65c42-baca-43db-bc1f-e97ded5a6b63",
"type": "PROCEDURE"
},
{
"id": "d0a42122-094e-4c93-a70c-fcadc21ce2ce",
"type": "PROCEDURE"
},
{
"id": "82c335f5-eb9e-48f6-916b-52f8a3c85a13",
"type": "PROCEDURE"
},
{
"id": "generated-procedure-notRequired-visa-CAN",
"type": "PROCEDURE"
}
]
}
}
},
Describing a Traveller
A Traveller is used to describe the specific travellers taking part in a trip. A traveller is an individual (PAX) person.
| Property | Type | Description |
|---|---|---|
| vaccinations | Object | List of vaccinations a traveller has received and disclosed. |
| nationality | string | ISO3 Country Code |
Describing a Vaccination
Fully Vaccinated by default
The response from the API defaults to travel rules for fully-vaccinated travellers.
The API supports filtering for COVID-19 vaccination status. By default, the API returns information for fully-vaccinated travellers.
| Property | Type | Description |
|---|---|---|
| status | String NOT_VACCINATED, FULLY_VACCINATED | Vaccination status of the traveller. |
| type | String COVID_19 | Type of vaccination. Currently only COVID_19 is supported. |
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.
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from San Francisco, SFO to San Diego, SAN. 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.
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from Berlin, SXF to Frankfurt am Main, FRA. Be sure to check official sources."
},
"borderCrossing": "REGIONAL"
Airport → Region (Within same country but different regions with no domestic info)
Example: COK → IN-DL
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from Kochi, COK to Delhi, IND. Be sure to check official sources."
},
"borderCrossing": "REGIONAL"
Example: SXF → DE-HE
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from Berlin, SXF to DE-HE. Be sure to check official sources."
},
"borderCrossing": "REGIONAL"
Region → Airport - (Within same country but different regions with no domestic info)
Example: DE-HE → SXF
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from DE-HE to Berlin, SXF. Be sure to check official sources."
},
"borderCrossing": "REGIONAL"
Region → Region (Within same country but different regions with no domestic info)
Example: DE-HE → DE-BR
"summary": {
"travelOpenness": "NO_INFORMATION",
"groupings": [],
"headline": "We don't have information for travel from DE-HE to DE-BR. Be sure to check official sources."
},
"borderCrossing": "REGIONAL"
Actual headlines are localized and may change
Headlines as part of the summary are fully localized and can be easily used to display information to the end users.
The outlined examples are a current snapshot and the exact copy of the messages may change as we continuously improve on making travel rules understandable.
Examples of invalid trips
Country -> Country (same country)
Example: CAN -> CAN
Country -> Region (region in same country)
Region -> Country (region in same country)
Example: CAN -> CA-ON
Country -> Airport (airport in same country)
Airport -> Country (airport in same country)
Example: CAN -> YYZ
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 /V2/trips response or as a stand-alone request for entry requirements under the /v2/procedures resource endpoint.
Looking at a /V2/trips response, the visa requirements are listed under the attributes summary with grouping type: VISAS (attributes.summary.groupings).
For a typical trip going one way from Canada(CAN) to Italy(ITA), a snippet below shows what to expect. The VISAS section has a list of the response ids which point to details about each visa requirement necessary for the trip.
{
"type": "VISAS",
"label": "Visa required",
"enforcement": "MANDATORY",
"included": [
{
"id": "9e170760-a9cc-446b-9389-4be9f4e29022"
},
{
"id": "90854258-561b-41bc-b3c9-ab0d46605485"
}
A search of the first id "9e170760-a9cc-446b-9389-4be9f4e29022" takes us to the included section of the trip response, where details of the visa requirement are listed below.
{
"id": "9e170760-a9cc-446b-9389-4be9f4e29022",
"type": "PROCEDURE",
"attributes": {
"country": "ITA",
"title": "No visa required",
"description": "To visit Italy for Business or Tourism, you do not require a visa. \n\nTo check permitted length of stay and other entry requirements, visit the government site.",
"more": [],
"enforcement": "NOT_REQUIRED",
"documentType": [
"VISA"
],
"documentLinks": [],
"tags": [
"international",
"land",
"air",
"sea",
"tourism",
"transit"
],
"source": {
"sourceType": "GOVERNMENT",
"title": "Ministry of Foreign Affairs of Italy",
"url": "https://vistoperitalia.esteri.it/home/en"
},
"lastUpdatedAt": "2021-12-23T22:21:00.000Z",
"createdAt": "2021-04-27T03:44:00.000Z",
"startDate": null,
"endDate": null,
"lengthOfStay": [
{
"value": 90,
"type": "DAYS",
"text": "90 days"
}
],
"travelPurpose": [
"TOURISM",
"TRANSIT"
],
"included": [
{
"code": "AUT",
"text": "Austria",
"type": "NATIONALITY"
},
[ ... ]
{
"code": "SGS",
"text": "South Georgia and the South Sandwich Islands",
"type": "NATIONALITY"
}
],
"category": "DOC_REQUIRED",
"subCategory": "BEFORE_ARRIVAL"
}
}
The visa requirement contains the following attributes as explained in the table below:
| Attribute | Description |
|---|---|
| Country | Issuing country |
| Title | Document Title |
| Description | Document Description |
| Enforcement | Level of enforcement of the requirement for entry. This can be Mandatory or Not Required |
| Document Type | Type of document. This can be a health pass, passenger locator form etc. In this case it is either a VISA or eVISA |
| Source | Sherpa's source, usually government. |
| Last Updated At | Last date sherpa° updated its database with information on this requirement. |
| Created At | When the requirement was created in Sherpa's repository |
| Start Date | When the requirement became active. This is usually empty since most visa requirements have been in place. |
| End Date | When the requirement is expected to end. This is also always empty since visa requirements unlike covid restrictions are not expected to end soon. |
| Length Of Stay | The number of days a traveller is allowed to stay in the destination country with a visa or without, if it is not enforced or required. |
| Travel Purpose | Purpose for which the visa requirement is issued. Can be Tourism, Business, Transit |
| Included | List of countries affected by the specific visa requirement. |
Test Window Translations
What is the Test window?
For our /trips endpoint certain procedures that include COVID-19 test results and different types of the test have an attribute tagged as testWindow. This attribute lists out when the test is to be done, the medical requirement type and how long.
Example: A PCR_Test needs to be done 72 hours before departure.
You can find more information with an example for the testWindow here
Clarifications
Can I retrieve information for both vaccinated and non-vaccinated traveller in one API request?
No, you must make two requests.
What is a fully vaccinated traveller?
Governments have different expectations from travellers. Sherpa provides information in the body of the response, but there is no way to personalize the information based on traveller vaccine types.
Updated over 1 year ago