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.