Trips Endpoint Response Reference

Example Response

In this section, you will find an example API response from the sample request found here, with details about each attribute and its possible values.

❗️

Note:

In the example response below, the various sections have been collapsed to allow for a better overall view of the response structure.

Comments have been added to indicate where objects were collapsed, and you can see the contents of each of the collapsed sections later on this page.

{
    "meta": {
        "copyright": "Sherpa",
        "version": "2.8.4"
    },
    "data": {
        "id": "1175946f-e080-4502-820e-837bffd4cc58",
        "type": "TRIP",
        "attributes": {
            "category": "ROUND_TRIP",
                        "segments": [...], // <---- segments of the trip
                        "summary": [...], // <---- important summarized facts about this trip
                        "outbound": {...}, // <---- summarized outbound segment incl. connections
                        "return": {...}, // <---- summarized return segment incl. connections
                },
                "relationships": {...}, // <---- list of all restriction and procedure IDs for the trip
        },
        "included": [...] // <---- all restriction/procedure details relevant to this trip
}

A response from the Trips endpoint can be broken down into the data and included structures. See the Data and Included sections below for more information on what can be found in each.

Data

Attribute

Type

Description

id

string

This trip’s unique identifier.

type

string

TRIP

category

string

Describes the variety of trip that was requested.

Possible values:
ROUND_TRIP: Includes both OUTBOUND and RETURN segments.
ONE_WAY_TRIP: Includes only OUTBOUND segments.

segments

array

A list of all the trip’s segments. See Segments.

summary

array

A list of the trip’s important headlines. See Summary.

outbound

object

A summarized outbound segment, incorporating connections. See Context Segments.

return

object

A summarized return segment, incorporating connections. See Context Segments.

relationships

object

A list of all the trip's applicable restriction and procedure IDs. See Relationships.

Segments

The segments attribute is an array of segment objects, each containing all the details for that particular leg of the trip. An example of one such segment object can be found below.

{
                    "segmentType": "OUTBOUND",
                    "segmentSubType": "TRANSIT",
                    "origin": {
                        "regionCode": "CA-ON",
                        "regionName": "Ontario",
                        "countryCode": "CAN",
                        "countryName": "Canada",
                        "airportCode": "YYZ",
                        "airportName": "Toronto"
                    },
                    "destination": {
                        "countryCode": "USA",
                        "countryName": "United States"
                    },
                    "travelMode": "AIR",
                    "departureDate": "2022-07-22T00:00:00.000Z",
                    "departureTime": "12:59",
                    "arrivalDate": "2022-07-22T00:00:00.000Z",
                    "arrivalTime": "12:59",
                    "borderCrossing": "INTERNATIONAL",
                    "summary": {
                        "headline": "Most travelers from Toronto, YYZ with proof of full COVID-19 vaccination can connect through United States, 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": [
                                    {
                                        "id": "d46ce91b-c8ba-4125-932b-456cb2374236"
                                    }
                                ]
                            },
                            {
                                "type": "DESTINATION_TRAVEL_RESTRICTIONS",
                                "label": "MANDATORY_DESTINATION_TRAVEL_RESTRICTIONS",
                                "enforcement": "MANDATORY",
                                "included": [
                                    {
                                        "id": "8675bb5f-1ae8-43e5-afab-80de64c0b665"
                                    },
                                    {
                                        "id": "generated-procedure-mandatory-covid-USA"
                                    }
                                ]
                            },
                            {
                                "type": "DESTINATION_DOCUMENTS",
                                "label": "MANDATORY_DESTINATION_DOCUMENTS",
                                "enforcement": "MANDATORY",
                                "included": [
                                    {
                                        "id": "72b16890-9e85-4804-9ab5-c7890b039b04"
                                    }
                                ]
                            },
                            {
                                "type": "LOCAL_RESTRICTIONS",
                                "label": "MANDATORY_LOCAL_RESTRICTIONS",
                                "enforcement": "MANDATORY",
                                "included": []
                            },
                            {
                                "type": "UPCOMING",
                                "label": "MANDATORY_UPCOMING",
                                "enforcement": "MANDATORY",
                                "included": []
                            },
                            {
                                "type": "VISAS",
                                "label": "No visa required",
                                "enforcement": "NOT_REQUIRED",
                                "included": [
                                    {
                                        "id": "8c29aed6-fa2f-407b-9d98-cb6feefe11db"
                                    }
                                ]
                            }
                        ]
                    }
                },

Attribute

Type

Description

segmentType

string

Describes the type of the trip segment.

Possible values:
OUTBOUND: Travelling towards the final destination.
RETURN: Travelling back from the final destination.

segmentSubType

string

Only used for the segment where the connecting location is the destination.

The segment from a connecting location to the final destination will not have this attribute.

Possible values:
TRANSIT: Used for layovers/connections.

origin

object

Describes the origin location for this segment.

Contains name(s) and code(s) for the origin country and/or region and/or airport.

destination

object

Describes the destination location for this segment.

Contains name(s) and code(s) for the destination country and/or region and/or airport.

travelMode

string

Possible values:
AIR
LAND
SEA

departureDate

string

Date of departure from the segment origin in YYYY-MM-DD format.

departureTime

string

Time of departure from the segment origin in HH:MM format.

arrivalDate

string

Date of arrival at the segment destination in YYYY-MM-DD format.

arrivalTime

string

Time of arrival at the segment destination in HH:MM format.

borderCrossing

string

Possible values:
INTERNATIONAL
REGIONAL
NO_BORDER_CROSSING

summary

object

Contains a summary headline for the segment and all relevant restriction/procedure IDs in groups. See Segment Summary.

Segment Summary

Attribute

Type

Description

headline

string

A short description of the level of restriction(s) applicable to this leg of the trip.

travelOpenness

string

Represents the destination country's entry restrictions, COVID-19 testing requirements, quarantine requirements, and vaccination requirements based on the origin country.

Possible values:
LEVEL_1:
Travel is open
LEVEL_2: Test & travel
LEVEL_3: Test & quarantine
LEVEL_4: Borders are closed

groupings

string

A list of groups of restrictions/procedures that apply to this leg of the trip. See Groupings.

Groupings

Attribute

Type

Description

type

string

A title that describes the sort of restrictions or procedure that can be found in the group.

The group contains restrictions or procedures of this type that may be relevant to this trip.

Possible values:
ORIGIN_TRAVEL_RESTRICTIONS: Restrictions that apply when departing the segment origin.
ORIGIN_DOCUMENTS: Documents required to depart the segment origin.
DESTINATION_TRAVEL_RESTRICTIONS: Restrictions that apply when arriving at the segment destination.
DESTINATION_DOCUMENTS: Documents required to enter the segment destination.
LOCAL_RESTRICTIONS: General restrictions applying to travellers within the segment destination (e.g. mask requirements)
UPCOMING: Restrictions/procedures taking effect within 30 days of the segment's travel dates.
VISAS
: Procedures for visa requirements when travelling to the segment destination based on traveller nationality.

label

string

Combination of the enforcement and type attributes of the grouping.

enforcement

string

The highest level of enforcement among all the restrictions/procedures in the group.

Possible values:
MANDATORY
RECOMMENDED
MAY_BE_REQUIRED
OPTIONAL
NOT_REQUIRED

included

array

A list of the unique IDs of all restrictions/procedures within the group.

Summary

The summary attribute is an array of objects intended to highlight various important requirements of the trip.

"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"
                }
            ],

Attribute

Type

Description

type

string

Describes the sort of requirement being highlighted.
Possible values:
COVID_19_TEST
QUARANTINE
DOC_REQUIRED
VISA

headline

string

A sentence that describes the requirement in general terms.

enforcement

string

Describes the level of enforcement for this particular requirement.

Possible values:
MANDATORY
RECOMMENDED
MAY_BE_REQUIRED
OPTIONAL
NOT_REQUIRED

Context Segments

The outbound and return attributes are created segment objects that incorporate details from all outbound or return segments respectively into context segments describing the entire outbound or return portion of the trip.

Besides the inclusion of the segmentSubType attribute being CONTEXT, these context segment objects follow the same structure as those within the segments attribute described here.

"outbound": {
                "segmentType": "OUTBOUND",
                "segmentSubType": "CONTEXT", // <---- this identifies it as a CONTEXT SEGMENT
                "origin": {
                    "regionCode": "CA-ON",
                    "regionName": "Ontario",
                    "countryCode": "CAN",
                    "countryName": "Canada",
                    "airportCode": "YYZ",
                    "airportName": "Toronto"
                },
                "departureDate": "2022-07-22T00:00:00.000Z",
                "departureTime": "12:59",
                "destination": {
                    "countryCode": "MEX",
                    "countryName": "Mexico"
                },
                "arrivalDate": "2022-07-22T00:00:00.000Z",
                "arrivalTime": "12:59",
                "travelMode": "AIR",
                "borderCrossing": "INTERNATIONAL",
                "summary": {
                    "headline": "Most travelers from Toronto, YYZ with proof of full COVID-19 vaccination can enter Mexico via United States.",
                    "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": "d46ce91b-c8ba-4125-932b-456cb2374236"
                                }
                            ]
                        },
                        {
                            "type": "DESTINATION_TRAVEL_RESTRICTIONS",
                            "label": "NOT_REQUIRED_DESTINATION_TRAVEL_RESTRICTIONS",
                            "enforcement": "NOT_REQUIRED",
                            "included": [
                                {
                                    "id": "57ab7fb3-ec16-4f01-8da2-fbd9c1301d96"
                                },
                                {
                                    "id": "bf14a075-ac7b-4e78-bc8f-3f546f85ff55"
                                },
                                {
                                    "id": "47e625dd-110b-4ce2-97b8-f46330fc957d"
                                }
                            ]
                        },
                        {
                            "type": "DESTINATION_DOCUMENTS",
                            "label": "RECOMMENDED_DESTINATION_DOCUMENTS",
                            "enforcement": "RECOMMENDED",
                            "included": [
                                {
                                    "id": "7eec65a1-603b-4ac9-8506-d9e9d311a2ad"
                                },
                                {
                                    "id": "74d49e05-4410-480c-b158-eba3049d5736"
                                }
                            ]
                        },
                        {
                            "type": "LOCAL_RESTRICTIONS",
                            "label": "MANDATORY_LOCAL_RESTRICTIONS",
                            "enforcement": "MANDATORY",
                            "included": [
                                {
                                    "id": "2cf83da6-3b2b-4809-a6df-49305934fae1"
                                }
                            ]
                        },
                        {
                            "type": "UPCOMING",
                            "label": "MANDATORY_UPCOMING",
                            "enforcement": "MANDATORY",
                            "included": []
                        },
                        {
                            "type": "VISAS",
                            "label": "No visa required",
                            "enforcement": "NOT_REQUIRED",
                            "included": [
                                {
                                    "id": "79343e59-e231-4898-a5f1-fb51771f54d6"
                                }
                            ]
                        }
                    ]
                }
            },

Relationships

The relationships object contains both a restrictions and procedures object within it. These show the complete list of applicable restrictions and procedure IDs respectively for the trip.

"relationships": {
            "restrictions": {
                "meta": {
                    "count": 3
                },
                "data": [
                    {
                        "id": "8675bb5f-1ae8-43e5-afab-80de64c0b665",
                        "type": "RESTRICTION"
                    },
                    {
                        "id": "57ab7fb3-ec16-4f01-8da2-fbd9c1301d96",
                        "type": "RESTRICTION"
                    },
                    {
                        "id": "e09d1ff6-e22e-47b4-bea9-14b0bf3faf6c",
                        "type": "RESTRICTION"
                    }
                ]
            },
            "procedures": {
                "meta": {
                    "count": 17
                },
                "data": [
                    {
                        "id": "72b16890-9e85-4804-9ab5-c7890b039b04",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "8c29aed6-fa2f-407b-9d98-cb6feefe11db",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "generated-procedure-mandatory-covid-USA",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "d46ce91b-c8ba-4125-932b-456cb2374236",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "bf14a075-ac7b-4e78-bc8f-3f546f85ff55",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "47e625dd-110b-4ce2-97b8-f46330fc957d",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "74d49e05-4410-480c-b158-eba3049d5736",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "7eec65a1-603b-4ac9-8506-d9e9d311a2ad",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "2cf83da6-3b2b-4809-a6df-49305934fae1",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "79343e59-e231-4898-a5f1-fb51771f54d6",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "4794a440-db77-4f38-bacf-83136a33b4ef",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "4b76c85f-871b-4288-ab5c-361ff74e6bb9",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "bf49195e-7698-4f4e-90d0-1caa3a4fe08c",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "a6b0f451-6001-457b-8546-62f075f231e7",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "bb39892f-14ea-4a77-b1ae-7df6d5aed382",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "796db632-063b-47e0-84bd-0e93193c3fb0",
                        "type": "PROCEDURE"
                    },
                    {
                        "id": "generated-procedure-notRequired-visa-CAN",
                        "type": "PROCEDURE"
                    }
                ]
            }
        }

Included

The included attribute is an array containing all the details about each restriction and/or procedure mentioned by their IDs throughout all the previous parts of the response.

Procedures:

Below is an example of a single procedure object from the included array.

❗️

Note:

Not every procedure will include every attribute as the included attributes depend on the type of procedure.

{
            "id": "72b16890-9e85-4804-9ab5-c7890b039b04",
            "type": "PROCEDURE",
            "attributes": {
                "country": "USA",
                "title": "Proof of negative pre-departure COVID-19 test results",
                "description": "...",
                "more": [
                    "..."
                ],
                "enforcement": "MANDATORY",
                "severity": 3,
                "documentType": [
                    "COVID_TEST_RESULT"
                ],
                "documentLinks": [],
                "medicalRequirementType": [
                    "ANTIGEN_TEST",
                    "NUCLEIC_ACID_TEST",
                    "RT_PCR_TEST",
                    "RT_LAMP_TEST",
                    "TMA_TEST"
                ],
                "testWindow": [
                    {
                        "condition": "BEFORE_DEPARTURE",
                        "type": "DAYS",
                        "value": 1,
                        "text": "1 day",
                        "medicalRequirementType": "ANTIGEN_TEST"
                    },
                    {
                        "condition": "BEFORE_DEPARTURE",
                        "type": "DAYS",
                        "value": 1,
                        "text": "1 day",
                        "medicalRequirementType": "NUCLEIC_ACID_TEST"
                    },
                    {
                        "condition": "BEFORE_DEPARTURE",
                        "type": "DAYS",
                        "value": 1,
                        "text": "1 day",
                        "medicalRequirementType": "RT_PCR_TEST"
                    },
                    {
                        "condition": "BEFORE_DEPARTURE",
                        "type": "DAYS",
                        "value": 1,
                        "text": "1 day",
                        "medicalRequirementType": "RT_LAMP_TEST"
                    },
                    {
                        "condition": "BEFORE_DEPARTURE",
                        "type": "DAYS",
                        "value": 1,
                        "text": "1 day",
                        "medicalRequirementType": "TMA_TEST"
                    }
                ],
                "labels": {
                    "ANTIGEN_TEST": "Antigen Test",
                    "BEFORE_DEPARTURE": "before departure",
                    "NUCLEIC_ACID_TEST": "Nucleic Acid Test",
                    "RT_PCR_TEST": "RT-PCR Test",
                    "RT_LAMP_TEST": "RT-LAMP Test",
                    "TMA_TEST": "TMA Test"
                },
                "tags": [
                    "international",
                    "air",
                    "tourism",
                    "medical",
                    "business",
                    "transit"
                ],
                "source": {
                    "sourceType": "GOVERNMENT",
                    "title": "CDC - FAQs",
                    "url": "https://www.cdc.gov/coronavirus/2019-ncov/travelers/testing-international-air-travelers.html"
                },
                "lastUpdatedAt": "2022-05-03T06:03:00.000Z",
                "createdAt": "2021-12-03T16:48:00.000Z",
                "startDate": "2021-12-06T00:00:00.000Z",
                "endDate": null,
                "travelPurpose": [
                    "TOURISM",
                    "MEDICAL",
                    "BUSINESS",
                    "TRANSIT"
                ],
                "included": [...],
                                "category": "DOC_REQUIRED",
                "subCategory": "BEFORE_ARRIVAL"
                    }

Attribute

Type

Description

id

string

The unique identifier for this procedure.

type

string

PROCEDURE

country

string

ISO-3 code of the country that implemented this procedure.

region

string

The code for the specific region this procedure applies to within that country (if applicable).

title

string

The title of the procedure.

description

string

The complete description of the procedure.

more

array

Any additional paragraphs of text that outline a more detailed description.

Mostly used for additional exemptions, edge cases, instructions or references.

enforcement

string

Describes the level of enforcement for this particular procedure.

Possible values.

severity

integer

A value from 0 to 5 representing the severity level of this restriction.

documentType

array

Only applies to procedures requiring documentation.

List of applicable document types

Possible values.

documentLinks

array

List of URLs leading to any documents or forms that relate to this procedure.

medicalRequirementType

array

Currently only applies to COVID-19 testing procedures.

List of acceptable COVID-19 test types for this procedure.

Possible values.

testWindow

array

Currently only applies to COVID-19 testing procedures.

List of acceptable test windows for each type of acceptable COVID-19 test for this procedure. See Test Windows.

tags

array

List of keywords describing the content area of the procedure.

Possible values.

source

object

See Sources.

lastUpdatedAt

string

Timestamp for when this procedure was last updated.

createdAt

string

Timestamp for when this procedure was added to the database.

startDate

string

Date when this procedure will take effect.

If null then the procedure is already in effect.

endDate

string

Date when this procedure will end.

If null then there is no information on when this procedure will end.

travelPurpose

string

Indicates the purpose of travel this procedure applies to. If empty, no particular purpose is included or excluded.

Possible values:
BUSINESS: For business purposes.
MEDICAL: For medical purposes such as attending surgery, staff of a surgical team, etc.
TOURISM: For touristic purposes only.

included

array

List of location objects with the name and code of the origin countries and/or nationalities subject to this procedure.

category

string

The category or variety of the procedure.

Possible values.

subCategory

string

Describes which stage of travel the procedure applies to.

Possible values.

defaultDurationInDays

int

Currently only applies to quarantine procedures.

The number of days required for quarantining as part of this procedure.

Restrictions:

Below is an example of a single restriction object from the included array.

❗️

Note:

Not every restriction will include every attribute as the included attributes depend on the type of restriction.

{
            "id": "e09d1ff6-e22e-47b4-bea9-14b0bf3faf6c",
            "type": "RESTRICTION",
            "attributes": {
                "country": "CAN",
                "title": "Travel is allowed with restrictions for vaccinated travelers",
                "description": "...",
                "more": [
                    "..."
                ],
                "severity": 1,
                "documentLinks": [],
                "tags": [
                    "international",
                    "fully_vaccinated",
                    "air"
                ],
                "source": {
                    "sourceType": "GOVERNMENT",
                    "title": "Government of Canada",
                    "url": "https://travel.gc.ca/travel-covid/travel-restrictions/flying#health-check"
                },
                "lastUpdatedAt": "2022-04-26T20:29:00Z",
                "createdAt": "2021-09-22T14:31:00Z",
                "startDate": "2021-09-27T00:00:00Z",
                "endDate": null,
                                "travelPurpose": [],
                "included": [...],
                                "category": "RESTRICTED_ENTRY",
                "subCategory": "ENTRY"
                    }

Attribute

Type

Description

id

string

The unique identifier for this restriction.

type

string

RESTRICTION

country

string

ISO-3 code of the country that implemented this restriction.

region

string

The code for the specific region this restriction applies to within that country (if applicable).

title

string

The title of the restriction.

description

string

The complete description of the restriction.

more

array

Any additional paragraphs of text that outline a more detailed description.

Mostly used for additional exemptions, edge cases, instructions or references.

severity

object

A value from 0 to 5 representing the severity level of this restriction.

documentLinks

array

List of URLs leading to any documents or forms that relate to this restriction.

tags

array

List of keywords describing the content area of the restriction.

Possible values.

source

object

See Sources.

lastUpdatedAt

string

Timestamp for when this restriction was last updated.

createdAt

string

Timestamp for when this restriction was added to the database.

startDate

string

Date when this restriction will take effect.

If null then the restriction is already in effect.

endDate

string

Date when this restriction will end.

If null then there is no information on when this restriction will end.

travelPurpose

array

Indicates the purpose of travel this restriction applies to. If empty, no particular purpose is included or excluded.

Possible values:
BUSINESS: For business purposes.
MEDICAL: For medical purposes such as attending surgery, staff of a surgical team, etc.
TOURISM: For touristic purposes only.

included

array

List of location objects with the name and code of the origin countries and/or nationalities subject to this restriction.

category

string

Describes the level of restrictiveness in place and what the restriction applies to.

Possible values.

subCategory

string

Describes which stage of travel the restriction applies to.

Possible values.

Test Windows

Test windows can either be in days or hours and are used to specify when various COVID-19 tests must be taken by a traveller for the purpose of conforming to a particular procedure as part of their trip.

Attribute

Type

Description

condition

string

Refers to when the test needs to be taken.

Possible values:
BEFORE_ARRIVAL
BEFORE_DEPARTURE
BEFORE_FINAL_BOARDING
AFTER_ARRIVAL
AFTER_DEPARTURE
AFTER_FINAL_BOARDING

type

string

Possible values:
DAYS
HOURS

value

integer

Number of days/hours.

text

string

Translated value and type attributes into a single string.

medicalRequirementType

string

List of acceptable COVID-19 test types for this procedure.

Possible values.

Sources

Each procedure or restriction object includes a source object to identify where Sherpa obtained the rest of the information about the procedure or restriction. Each source object follows this format.

Attribute

Type

Description

sourceType

string

Possible values:
GOVERNMENT
AIRLINE
AIRPORT

title

string

The name of the source.

url

string

The direct link to the source of the restriction/procedure.


Did this page help you?