Technical Overview

API Versions

TripAdvisor periodically releases updated versions of its API. As breaking changes are introduced, a new version number will be made available. These versions are currently available:

 

Version

Launch Date

Status

2.0

December 2016

Data limited to content described here

Keys issued prior to this date will continue to have original access level.

2.0

August 2014

Available until at least August 2017

1.0

April 2013

Available until at least August 2016

 

 

Key updates in Version 2.0

  • Syntax Updates: A number of field names throughout the API responses have been updated to consistently use snake_case. Additionally, when the same data is returned as part of different method responses, e.g., user data, it will be formatted consistently.

  • Localizations: All field names have been standardized to be returned in English only, so the field name will be consistent regardless of which language was requested. Field values may include localizations, depending upon the language requested.

 

Authentication / Security

All API requests must be made over https. Note: The partner will need to set a user agent and use api.tripadvisor.com for the API calls to ensure that all requests are sent through.

 

Please safeguard your access key. To include it with each request, set it as the value of the X-TripAdvisor-API-Key header. If you need to make API calls from client code, be aware this may expose your key to other scripts and browser extensions on the client.

 

TripAdvisor reserves the right to revoke an access key at any time and issue a new one, if a key has leaked or is being misused.

 

Rate Limits

TripAdvisor sets daily and per-second call limits on each key used to access the Content API. Users of our Content API are set by default to 50 calls/second, and 1,000 calls/day during development and QA. Once approved for launch, the daily calls limit is increased to 10,000.

 

The partner API returns an HTTP status code of 429, “too many requests”, when either the per-second or per-day limits are reached. The two cases are distinguished by the error code in the response body. The response body will contain an error message in a JSON object. For the per-second limit, the response body will be like:

{
 "error": {
  "message": "Maximum number of requests per second exceeded: (Max: 50 per sec)",
  "code": "150",
  "type": "TooManyRequestsException"
 }
}

 

For the daily limit, the response body will be like:

{
"error": {   "message": "Maximum number of daily requests exceeded: (Max: 100000 per day)",   "code": "151",   "type": "TooManyRequestsException" } }

Caching

You must update TripAdvisor content daily. TripAdvisor recommends that you cache the content from API responses for 24 hours. This allows your application to show content more quickly if it has been requested before. Caching also reduces the load on TripAdvisor’s content servers. Do not use the API to pre-fetch content for your entire inventory, request only the content you need.

TripAdvisor has implemented HTTP cache headers.  All TripAdvisor API traffic is routed through a CDN [Content Delivery Network], which can cache the content locally so that it can be served more quickly.  TripAdvisor has added cache control headers to API responses so that they can be cached in the CDN, giving partners who make frequent repeated calls for the same location better response time and less impact on their API call quotas.

Most API content is marked as cacheable for one hour.  Any request without a partner-specific query parameter (key or cache-key) will not be cached.  Content in the Review Express API will not be cached.

If you are using the X-TripAdvisor.API-Key header for authentication, we recommend that you add a query parameter cache-key, with the MD5 hash of your partner key as the value.

Errors

Error

Code

Description

Sample

Invalid client key

160

Your partner key was incorrect

{
"error": {
  "message": "invalid client key: 3cacf",
 "code": "160",
 "type": "UnauthorizedException"
}
}

Too many requests

150

Maximum requests per second exceeded

{
"error": {
  "message": "Maximum number of requests per second exceeded: (Max: 25 per sec)",
  "code": "150",
  "type": "TooManyRequestsException"
}
}

Too many requests

151

Maximum requests per day exceeded


{
"error": {
"message": "Maximum number of daily requests exceeded: (Max: 1000 per day)",
  "code": "151",
  "type": "TooManyRequestsException"
}
}

Invalid location_id

101

The location_id being passed is not recognized by TripAdvisor

{
"error": {
"message": "The location was not found.","code": "101",
"type": "NotFoundException"
}
}

Method not found

101

An invalid connection was requested

{
 "error": {
  "message": "The method was not found.",
  "code": "101",
  "type": "NotFoundException"
 }
}

Invalid connection

120

The location_id passed is not valid for this connection

{
"error": {
  "message": "Cannot view this connection at this level.",
  "code": "120",
  "type": "BadRequestException"
 }
}