Requirements API FAQ
The following pages contain some of the frequently asked questions and standard troubleshooting guides for issues around integrating the Sherpa° API.
Where does the information come from?
Data is aggregated from various trusted sources. Most of the information comes directly from Government Website, Travel Organizations & Services.
Source Examples:
- Canadian Government
- Australia Home Affairs
- Singapore Ministry of Health
- Coronavirus and Travel in the United States
- UK Government
- CDC
How often is information updated
Information is collected 24/7 and fresh data is pushed on an hourly basis after passing quality control. It is not recommended to cache the data for longer than an hour.
Language support
The content is localized to several languages. See the language support page.
Open API
Our API specification complies with the Open API standard, identified by IATA as the best practice for the airline industry.
What are all your endpoints and what methods do they use?
Sherpa° currently as part of our Requirements API currently have below endpoints available to use with methods listed below
| EndPoint Name | Method Utilized | Description |
|---|---|---|
| Trips | POST | The trips endpoint is our most up to date and is a starting area we highly recommend for all customers to review. This endpoint has been developed from a traveler's journey perspective. |
| Restrictions | GET | Our restrictions endpoint allows customers to dive deeper into our dataset. It is possible to get restrictions that apply for vaccinated or unvaccinated traveller's, restrictions filtered based on countries or categories. |
| Procedures | GET | Our procedures endpoint allows customers to dive deeper into our dataset. It is possible to get procedures that apply for vaccinated or unvaccinated traveller's, restrictions filtered based on countries or categories. Our VISA information is also displayed as procedures in our data. |
| Countries | GET | Our Countries endpoint presents data from a country overview, data based on specific countries as an example can be reviewed using this. |
| Regions | GET |
API Rate Limit and Response Size Limitation
All our API endpoints currently impose a rate limit of 100 requests/second. In a scenario where the rate limit will hinder a particular business case, please get in touch with our support team to review and partner with you in creating a solution. We have a hard physical limit of 10 MB for response size. We highly recommend at present to chunk data where possible.
Below is an example scenario :
Use Case: I want to utilize the /restriction endpoint to get all available restrictions on your database for review, but I get a 500 error when making the request.
Solution: It would be advisable to utilize the filter[countries] to chunk the data and, for each request, get restrictions for a set of 25-50 countries.
Sherpa API HTTP Error Codes
While trying out the Sherpa API endpoints, there are scenarios where errors could come up due to misplaced keywords, typos and/or wrong keys. We have collected a few common errors related to the Sherpa API platform below.
| Error Codes | Description |
|---|---|
| 400 | Validation error, bad request, likely due to missing expected input, misspelled keyword or invalid token/key. |
| 401 | Unauthorized, likely when you attempt to access the endpoint without a registered id/key. |
| 403 | Permission denied, probably due to (incorrect) affiliate ID / Key used on the wrong platform |
| 404 | Not found. The current request is not defined by this API. Likely due to a wrong or misspelled endpoint address. |
| 500 | Internal Server Error, usually due to missing internal parameters |
| 502 | Bad gateway, usually happens when the server connection is terminated due to timeout or very large size of response data. |
Can Sherpa data be cached via API?
Yes, data via our API is cachable. Our /Trips endpoint utilizes the POST method and has cache-control set in our headers with value as public, max-age =3600 seconds
Can we request multiple languages in one API request?
Our API at present does not support this. Our supported languages are available here, we will display only the requested language in the response.
What timezone are restrictions/procedures stored in for your API?
All restrictions and procedure data are stored in UTC in our database.
Certain airports are not on your list. What is the process to get these airports added in for us?
We highly suggest passing country code instead of airport code where possible. The end-users will receive the exact travel requirements. If the passing of country code does not meet your business requirements, we add airports to our database on a bi-monthly basis. If there is a list of airports your travellers visit that isn't supported by sherpa°, please reach out to your Partner Success Manager with the airport three-letter codes and some traffic data for review by our product team.
What are your supported headers for API request?
Our WebApp and trip element solutions utilize our /trips endpoint. Our /trips endpoint followed the POST method and below is a list of headers in the options message:
access-control-allow-headers: x-sherpa-deviceId,DNT,User-Agent,X-User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,sfdc_stack_depth
A CORS error will be visible in the console and network tabs if any custom headers are added to the request. It is recommended to remove any custom headers.
Can you provide a list of possible documentTypes for sherpa° visa procedures?
For documentTypes, the possible values are:
| documentTypes |
|---|
| E_VISA |
| VISA |
| ETA |
| EMBASSY_VISA |
For visa procedures, the possible values are:
| Visa Procedures |
|---|
| Electronic travel authorization |
| Electronic visitor visa |
| Visitor visa |
| ESTA |
| Visa on arrival |
| Visa not required |
Tags
Content is sometimes tagged for additional context in the sherpa° system. Below is the list of currently used tags and their descriptions.
| Tag Name | Tag Description | Tag Generation Details |
|---|---|---|
| international | Is present when a restriction/procedure applies to an international traveller (one who is crossing an international border to enter the country/region). Both international and domestic tags can be present, indicating that the restriction/procedure applies to all travellers. | |
| domestic | Is present when a restriction/procedure applies to a domestic traveller (one who is crossing a domestic border to enter the region e.g. across state/subdivision lines). Both international and domestic tags can be present, indicating that the restriction/procedure applies to all travellers. | |
| air | Tag is present when a restriction/procedure applies to travellers crossing borders by air. Multiple travel mode tags can be present meaning that the restriction/procedure applies to all of the listed forms of travel | |
| land | Same as travelMode air | |
| sea | Same as travelMode air | |
| transit | The transit tag appears on both restrictions and procedures but can appear from different sources internally. The tag has the same meaning regardless: "This tag indicates that a restriction/procedure is applicable to travellers transiting through the country." | Procedures: when a procedure is marked as travelPurpose: TRANSIT , this tag will be generated. Restrictions: Restrictions follow the same tag generation as procedures but includes an additional criteria: when restrictionSubType: TRANSIT is present. |
| business | This tag indicates that a restriction/procedure is applicable to travellers entering/exiting a country for the given purpose of travel. | All travelPurpose tags are generated based on the procedure logic above. travelPurpose tags always exist on visa procedures. The same is not true for other procedures. Unless explicitly defined, these tags do not appear on all procedures and in general can be interpreted as "this procedure applies for all travel purposes" when none appear. |
| medical | Same as travelPurpose business | |
| tourism | Same as travelPurpose business | |
| fully_vaccinated | Indicates whether a restriction/procedure applies to ONLY fully vaccinated (COVID-19) travellers | This tag is generated when a restriction/procedure is applicable to ONLY fully vaccinated (COVID-19) travellers. When neither fully_vaccinated or not_vaccinated tags are present, the restriction/procedure can be interpreted as "this applies to everybody regardless of vaccination status" Learn more about vaccination tags. |
| not_vaccinated | Indicates whether a restriction/procedure applies to ONLY unvaccinated (COVID-19) travellers | This tag is generated when a restriction/procedure is applicable to ONLY unvaccinated (COVID-19) travellers. When neither fully_vaccinated or not_vaccinated tags are present, the restriction/procedure can be interpreted as "this applies to everybody regardless of vaccination status" Learn more about vaccination tags. |
How does the Vaccination Tag work?
As vaccinations become more prevalent world wide, governments are starting to introduce differences in procedures and restrictions for vaccinated travellers. Common examples are relaxed quarantine and covid testing requirements for fully vaccinated traveller's.
If a Procedure or Restriction changes for vaccinated traveller's, it will now become two entries. The one for unvaccinated traveller's can include all information, including vaccination exemptions, but the one for vaccinated traveller's should include information for vaccinated traveller's only.
-
Restrictions & Procedures now have a
vaccinationStatustag.
The potential values for vaccinationStatus are:FULLY_VACCINATED- This procedure/restriction applies to traveller's who are fully vaccinated only.NOT_VACCINATED- This procedure/restriction applies to traveller's who are not vaccinated. We still include vaccination details in the description & exemptions for these entries.- If you see both of the above values in
vaccinationStatus, or neither of them, the procedure/restriction applies to everyone regardless of vaccination status.
-
Any country with changes for vaccinated traveller's must include a "proof of vaccination" procedure. Remember, traveller's will need to prove that they are vaccinated! Note that different countries define this differently, with some saying both doses is enough, and some saying that traveller's must be a certain number of days post vaccination (usually 10 or 14). This procedure should have a documentType of
COVID_19_VACCINATION.
Resultset differences between /trips and other endpoints
Please note that for API /trips endpoint leaves it blank and provides data equivalent to FULLY_VACCINATED unless the vaccinated toggle is passed.
The expectation on our other endpoints excluding /trips endpoint would be: No filter is passed, so both tags are visible
FULLY_VACCINATEDandNOT_VACCINATED.
Updated 6 months ago