openapi: 3.1.0
info:
title: Tripadvisor Content API
description: >-
The Tripadvisor Content API provides developers with access to Tripadvisor's
extensive dataset of more than 7.5 million locations, 1 billion reviews and
opinions, and content in 29 languages. The API includes endpoints for location
search, nearby search, location details, location photos, and location reviews,
enabling developers to integrate rich travel content into their websites and
applications. Locations are defined within this API as hotels, restaurants, or
attractions. The first 5,000 API calls per month are free for initial
development and testing.
version: '1.0'
contact:
name: Tripadvisor Developer Support
url: https://developer-tripadvisor.com/content-api/
termsOfService: https://developer-tripadvisor.com/content-api/terms-of-use/
externalDocs:
description: Tripadvisor Content API Documentation
url: https://tripadvisor-content-api.readme.io/reference/overview
servers:
- url: https://api.content.tripadvisor.com/api/v1
description: Production Server
tags:
- name: Location Details
description: >-
Retrieve comprehensive information about a specific location including
name, address, rating, and Tripadvisor listing URLs.
- name: Location Photos
description: >-
Access high-quality recent photos for a specific location in multiple
size formats.
- name: Location Reviews
description: >-
Retrieve the most recent reviews for a specific location, up to 5 reviews
per request.
- name: Location Search
description: >-
Search for locations by keyword query or geographic proximity. Returns up
to 10 matching locations per request.
security:
- apiKeyQuery: []
paths:
/location/search:
get:
operationId: searchForLocations
summary: Search for Locations
description: >-
Returns up to 10 locations found by the given search query. You can use
category, phone number, address, and latitude/longitude to search with
more accuracy. Locations include hotels, restaurants, and attractions.
tags:
- Location Search
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/Category'
- $ref: '#/components/parameters/Phone'
- $ref: '#/components/parameters/Address'
- $ref: '#/components/parameters/LatLong'
- $ref: '#/components/parameters/Radius'
- $ref: '#/components/parameters/RadiusUnit'
- $ref: '#/components/parameters/Language'
responses:
'200':
description: Successful location search results
content:
application/json:
schema:
$ref: '#/components/schemas/LocationSearchResponse'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/location/nearby_search:
get:
operationId: searchForNearbyLocations
summary: Search for Nearby Locations
description: >-
Returns up to 10 locations found near the given latitude and longitude.
You can use category, phone number, and address to search with more
accuracy. Useful for finding hotels, restaurants, and attractions in
proximity to a specific geographic point.
tags:
- Location Search
parameters:
- $ref: '#/components/parameters/LatLongRequired'
- $ref: '#/components/parameters/Category'
- $ref: '#/components/parameters/Phone'
- $ref: '#/components/parameters/Address'
- $ref: '#/components/parameters/Radius'
- $ref: '#/components/parameters/RadiusUnit'
- $ref: '#/components/parameters/Language'
responses:
'200':
description: Successful nearby search results
content:
application/json:
schema:
$ref: '#/components/schemas/LocationSearchResponse'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/location/{locationId}/details:
get:
operationId: getLocationDetails
summary: Get Location Details
description: >-
Returns comprehensive information about a specific location such as
name, address, rating, ranking, and URLs for the listing on
Tripadvisor. Works for hotels, restaurants, and attractions.
tags:
- Location Details
parameters:
- $ref: '#/components/parameters/LocationId'
- $ref: '#/components/parameters/Language'
- $ref: '#/components/parameters/Currency'
responses:
'200':
description: Successful location details response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationDetails'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Location not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/location/{locationId}/photos:
get:
operationId: getLocationPhotos
summary: Get Location Photos
description: >-
Returns up to 5 high-quality recent photos for a specific location.
Photos are available in multiple sizes including thumbnail (50x50),
small (150x150), medium (max 250px), large (max 550px), and original
resolution.
tags:
- Location Photos
parameters:
- $ref: '#/components/parameters/LocationId'
- $ref: '#/components/parameters/Language'
responses:
'200':
description: Successful location photos response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationPhotosResponse'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Location not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/location/{locationId}/reviews:
get:
operationId: getLocationReviews
summary: Get Location Reviews
description: >-
Returns up to 5 of the most recent reviews for a specific location.
Includes review text, rating, title, publication date, and information
about the reviewer.
tags:
- Location Reviews
parameters:
- $ref: '#/components/parameters/LocationId'
- $ref: '#/components/parameters/Language'
responses:
'200':
description: Successful location reviews response
content:
application/json:
schema:
$ref: '#/components/schemas/LocationReviewsResponse'
'400':
description: Bad request due to invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized due to missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Location not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
apiKeyQuery:
type: apiKey
name: key
in: query
description: >-
API key passed as a query parameter. Obtain your key by registering at
the Tripadvisor Developer Portal.
parameters:
LocationId:
name: locationId
in: path
required: true
description: >-
The unique identifier for a Tripadvisor location (hotel, restaurant, or
attraction).
schema:
type: integer
example: 60745
SearchQuery:
name: searchQuery
in: query
required: true
description: >-
The text query to search for matching locations.
schema:
type: string
example: "Eiffel Tower"
Category:
name: category
in: query
required: false
description: >-
Filter results by location category type.
schema:
type: string
enum:
- hotels
- attractions
- restaurants
- geos
Phone:
name: phone
in: query
required: false
description: >-
Phone number to search for a specific location.
schema:
type: string
Address:
name: address
in: query
required: false
description: >-
Address string to improve search accuracy.
schema:
type: string
LatLong:
name: latLong
in: query
required: false
description: >-
Latitude and longitude pair to bias search results toward a specific
geographic area. Format is latitude,longitude.
schema:
type: string
pattern: '^-?\d+\.?\d*,-?\d+\.?\d*$'
example: "48.8584,2.2945"
LatLongRequired:
name: latLong
in: query
required: true
description: >-
Latitude and longitude pair for the center of the nearby search.
Format is latitude,longitude.
schema:
type: string
pattern: '^-?\d+\.?\d*,-?\d+\.?\d*$'
example: "48.8584,2.2945"
Radius:
name: radius
in: query
required: false
description: >-
The radius distance from the latLong point to filter results.
schema:
type: number
format: float
RadiusUnit:
name: radiusUnit
in: query
required: false
description: >-
The unit of measurement for the radius parameter.
schema:
type: string
enum:
- km
- mi
default: km
Language:
name: language
in: query
required: false
description: >-
The language code for the response content. Tripadvisor supports 29
languages.
schema:
type: string
default: en
example: en
Currency:
name: currency
in: query
required: false
description: >-
The currency code for pricing information in the response.
schema:
type: string
default: USD
example: USD
schemas:
LocationSearchResponse:
type: object
description: >-
Response containing a list of locations matching the search criteria.
properties:
data:
type: array
description: >-
Array of location summary objects matching the search query, up to
10 results.
items:
$ref: '#/components/schemas/LocationSummary'
LocationSummary:
type: object
description: >-
A summary representation of a Tripadvisor location returned in search
results.
properties:
location_id:
type: string
description: >-
The unique Tripadvisor identifier for this location.
name:
type: string
description: >-
The display name of the location.
address_obj:
$ref: '#/components/schemas/Address'
LocationDetails:
type: object
description: >-
Comprehensive information about a specific Tripadvisor location.
properties:
location_id:
type: string
description: >-
The unique Tripadvisor identifier for this location.
name:
type: string
description: >-
The display name of the location.
description:
type: string
description: >-
A detailed text description of the location.
web_url:
type: string
format: uri
description: >-
The URL of the location's page on Tripadvisor.
address_obj:
$ref: '#/components/schemas/Address'
ancestors:
type: array
description: >-
Array of parent geographic locations in the hierarchy.
items:
$ref: '#/components/schemas/Ancestor'
latitude:
type: string
description: >-
The latitude coordinate of the location.
longitude:
type: string
description: >-
The longitude coordinate of the location.
timezone:
type: string
description: >-
The timezone of the location.
phone:
type: string
description: >-
The phone number of the location.
website:
type: string
format: uri
description: >-
The official website URL of the location.
write_review:
type: string
format: uri
description: >-
URL to write a review for this location on Tripadvisor.
ranking_data:
$ref: '#/components/schemas/RankingData'
rating:
type: string
description: >-
The overall rating of the location on a scale of 1 to 5.
rating_image_url:
type: string
format: uri
description: >-
URL of the rating bubble image.
num_reviews:
type: string
description: >-
The total number of reviews for this location.
review_rating_count:
type: object
description: >-
Breakdown of review counts by rating level (1-5).
additionalProperties:
type: string
photo_count:
type: string
description: >-
The total number of photos available for this location.
see_all_photos:
type: string
format: uri
description: >-
URL to view all photos on Tripadvisor.
price_level:
type: string
description: >-
The price level indicator (e.g., $, $$, $$$, $$$$).
hours:
$ref: '#/components/schemas/Hours'
cuisine:
type: array
description: >-
Array of cuisine types for restaurant locations.
items:
$ref: '#/components/schemas/Tag'
category:
$ref: '#/components/schemas/Tag'
subcategory:
type: array
description: >-
Array of subcategory classifications for this location.
items:
$ref: '#/components/schemas/Tag'
groups:
type: array
description: >-
Array of category groups this location belongs to.
items:
$ref: '#/components/schemas/Group'
trip_types:
type: array
description: >-
Array of trip type ratings for this location.
items:
$ref: '#/components/schemas/TripType'
awards:
type: array
description: >-
Array of awards received by this location.
items:
$ref: '#/components/schemas/Award'
Address:
type: object
description: >-
The physical address of a location.
properties:
street1:
type: string
description: >-
The primary street address line.
street2:
type: string
description: >-
The secondary street address line.
city:
type: string
description: >-
The city name.
state:
type: string
description: >-
The state or province name.
country:
type: string
description: >-
The country name.
postalcode:
type: string
description: >-
The postal or ZIP code.
address_string:
type: string
description: >-
The full formatted address as a single string.
Ancestor:
type: object
description: >-
A parent geographic location in the location hierarchy.
properties:
level:
type: string
description: >-
The level in the geographic hierarchy (e.g., City, Region, Country).
name:
type: string
description: >-
The name of the ancestor location.
location_id:
type: string
description: >-
The Tripadvisor location ID of the ancestor.
RankingData:
type: object
description: >-
Ranking information for the location within its category and geography.
properties:
geo_location_id:
type: string
description: >-
The Tripadvisor ID of the geographic area for ranking.
ranking_string:
type: string
description: >-
A human-readable ranking string.
geo_location_name:
type: string
description: >-
The name of the geographic area for ranking.
ranking_out_of:
type: string
description: >-
The total number of locations in the ranking category.
ranking:
type: string
description: >-
The numeric rank position.
Tag:
type: object
description: >-
A category or classification tag.
properties:
name:
type: string
description: >-
The display name of the tag.
localized_name:
type: string
description: >-
The localized display name of the tag.
Group:
type: object
description: >-
A category group with associated sub-categories.
properties:
name:
type: string
description: >-
The name of the group.
localized_name:
type: string
description: >-
The localized name of the group.
categories:
type: array
description: >-
Array of category tags within this group.
items:
$ref: '#/components/schemas/Tag'
TripType:
type: object
description: >-
Rating data for a specific type of trip.
properties:
name:
type: string
description: >-
The trip type name (e.g., business, couples, family).
localized_name:
type: string
description: >-
The localized trip type name.
value:
type: string
description: >-
The count of reviews for this trip type.
Award:
type: object
description: >-
An award or recognition received by the location.
properties:
award_type:
type: string
description: >-
The type of award.
year:
type: string
description: >-
The year the award was given.
images:
type: object
description: >-
Image URLs for the award badge.
properties:
small:
type: string
format: uri
description: >-
URL for the small award image.
large:
type: string
format: uri
description: >-
URL for the large award image.
display_name:
type: string
description: >-
The display name of the award.
Hours:
type: object
description: >-
Operating hours information for the location.
properties:
periods:
type: array
description: >-
Array of time periods when the location is open.
items:
type: object
properties:
open:
type: object
description: >-
The opening time details.
properties:
day:
type: integer
description: >-
Day of the week (0 = Sunday, 6 = Saturday).
minimum: 0
maximum: 6
time:
type: string
description: >-
The opening time in 24-hour format (HHMM).
close:
type: object
description: >-
The closing time details.
properties:
day:
type: integer
description: >-
Day of the week (0 = Sunday, 6 = Saturday).
minimum: 0
maximum: 6
time:
type: string
description: >-
The closing time in 24-hour format (HHMM).
weekday_text:
type: array
description: >-
Array of human-readable strings describing hours for each day of
the week.
items:
type: string
LocationPhotosResponse:
type: object
description: >-
Response containing photos for a specific location.
properties:
data:
type: array
description: >-
Array of photo objects for the location, up to 5 photos.
items:
$ref: '#/components/schemas/Photo'
Photo:
type: object
description: >-
A photo associated with a Tripadvisor location.
properties:
id:
type: integer
description: >-
The unique identifier for this photo.
is_blessed:
type: boolean
description: >-
Whether this photo has been marked as a featured photo.
caption:
type: string
description: >-
The caption text for the photo.
published_date:
type: string
format: date-time
description: >-
The date and time the photo was published.
images:
$ref: '#/components/schemas/PhotoImages'
album:
type: string
description: >-
The album category this photo belongs to.
source:
type: object
description: >-
Information about who uploaded the photo.
properties:
name:
type: string
description: >-
The name of the photo contributor.
localized_name:
type: string
description: >-
The localized name of the photo contributor.
user:
$ref: '#/components/schemas/UserReference'
PhotoImages:
type: object
description: >-
Available image sizes for a photo.
properties:
thumbnail:
$ref: '#/components/schemas/ImageSize'
small:
$ref: '#/components/schemas/ImageSize'
medium:
$ref: '#/components/schemas/ImageSize'
large:
$ref: '#/components/schemas/ImageSize'
original:
$ref: '#/components/schemas/ImageSize'
ImageSize:
type: object
description: >-
An image at a specific size with dimensions.
properties:
height:
type: integer
description: >-
The height of the image in pixels.
width:
type: integer
description: >-
The width of the image in pixels.
url:
type: string
format: uri
description: >-
The URL to access the image at this size.
LocationReviewsResponse:
type: object
description: >-
Response containing reviews for a specific location.
properties:
data:
type: array
description: >-
Array of review objects for the location, up to 5 reviews.
items:
$ref: '#/components/schemas/Review'
Review:
type: object
description: >-
A user review for a Tripadvisor location.
properties:
id:
type: integer
description: >-
The unique identifier for this review.
lang:
type: string
description: >-
The language code of the review.
location_id:
type: integer
description: >-
The location ID this review is for.
published_date:
type: string
format: date-time
description: >-
The date and time the review was published.
rating:
type: integer
description: >-
The rating given by the reviewer on a scale of 1 to 5.
minimum: 1
maximum: 5
helpful_votes:
type: integer
description: >-
The number of helpful votes this review has received.
rating_image_url:
type: string
format: uri
description: >-
URL of the rating bubble image for this review.
url:
type: string
format: uri
description: >-
URL of the review on Tripadvisor.
text:
type: string
description: >-
The full text content of the review.
title:
type: string
description: >-
The title of the review.
trip_type:
type: string
description: >-
The type of trip associated with this review.
travel_date:
type: string
description: >-
The date of travel associated with this review.
user:
$ref: '#/components/schemas/UserReference'
subratings:
type: object
description: >-
Sub-rating scores for specific aspects of the location.
additionalProperties:
type: object
properties:
name:
type: string
description: >-
The name of the sub-rating category.
rating_image_url:
type: string
format: uri
description: >-
URL of the rating bubble image for this sub-rating.
value:
type: string
description: >-
The sub-rating value.
UserReference:
type: object
description: >-
Reference to a Tripadvisor user who contributed content.
properties:
username:
type: string
description: >-
The username of the contributor.
user_location:
$ref: '#/components/schemas/Address'
avatar:
type: object
description: >-
Avatar images for the user.
properties:
thumbnail:
type: string
format: uri
description: >-
URL of the user's thumbnail avatar.
small:
type: string
format: uri
description: >-
URL of the user's small avatar.
large:
type: string
format: uri
description: >-
URL of the user's large avatar.
Error:
type: object
description: >-
Error response returned when a request fails.
properties:
error:
type: object
properties:
message:
type: string
description: >-
A human-readable error message describing what went wrong.
type:
type: string
description: >-
The error type classification.
code:
type: integer
description: >-
A numeric error code.