Recommendations requests

A Recommendations request takes a natural-language query and a geographic scope, and returns a ranked set of recommended Locations and Experiences. Each result may include the review snippets that support it. Recommendations only supports POST requests.

A request is an HTTP POST to a URL in the form:

https://terra.tripadvisor.com/api/recommendations/search

Pass all fields in the JSON request body. For example:

curl -X POST "https://terra.tripadvisor.com/api/recommendations/search?version=1" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: API_KEY" \
  -d '{
    "query": "quiet wine bar with outdoor seating for an anniversary",
    "geo": { "id": 187147 },
    "top_level_categories": ["Eat & Drink"],
    "limit": 5,
    "response_preference": "quality"
  }'

The request body is strict. A field the schema does not define returns 400 rather than being ignored.

query

Required, and must not be empty. The natural-language request. Express constraints in the query text — for example "kid-friendly", "under €30", "walkable from the station". There are no separate parameters for them.

geo

Required. The geographic scope, given in one of three forms:

• search_area — an explicit centroid and radius.
• id — a Tripadvisor Geo ID, resolved with Geo Details.
• name — a destination name, such as "Paris", "Boston MA" or "Brooklyn, New York, USA".

Each field is individually optional, and when more than one is supplied they are applied in that order of precedence: search_area overrides both id and name, and id overrides name.

The geo object itself is required, but it may be empty. An empty geo causes Tripadvisor to infer the destination from the query text. Supplying any form of geo overrides whatever the query text implies.

top_level_categories

Filters results by category. One or more of Accommodation, Eat & Drink, Attraction, Experience. If omitted, all categories are eligible.

limit

The maximum number of Locations to return. Defaults to 5.

exclude_location_ids

Location IDs to omit from the results. Pass the IDs returned by a previous request to retrieve further results for the same query.

response_preference

The trade-off between response speed and recommendation quality. One of quality (default) or speed.

Recommendations responses

The response contains a search_results array. Each entry has a type of either location or experience, and populates the corresponding object. An experience result carries its own providers and tags, so both shapes must be handled.

Each entry may carry a review_sources array of supporting review snippets. The array can be empty; a recommendation is not guaranteed to have citations.

Billing

Each call is billed as one entity, regardless of limit. See Usage-based Pricing.

Note: review snippets must be shown with attribution and linked back to Tripadvisor, as with any review content. See Linking Policy.

Examples

Recommend restaurants in a named city

curl -X POST "https://terra.tripadvisor.com/api/recommendations/search?version=1" \
  -H "Content-Type: application/json" -H "X-API-Key: API_KEY" \
  -d '{ "query": "family-friendly lunch near the museum district",
        "geo": { "name": "Amsterdam" },
        "top_level_categories": ["Eat & Drink"] }'

Retrieve the next set of results

curl -X POST "https://terra.tripadvisor.com/api/recommendations/search?version=1" \
  -H "Content-Type: application/json" -H "X-API-Key: API_KEY" \
  -d '{ "query": "family-friendly lunch near the museum district",
        "geo": { "name": "Amsterdam" },
        "exclude_location_ids": [190420, 190421, 190422] }'

Favour latency over ranking quality

curl -X POST "https://terra.tripadvisor.com/api/recommendations/search?version=1" \
  -H "Content-Type: application/json" -H "X-API-Key: API_KEY" \
  -d '{ "query": "rooftop bar with a view",
        "geo": { "id": 187147 },
        "response_preference": "speed" }'

Related

• Geo Details — resolve a destination to a geo_id
• Location Details — the full record for a recommended Location
• Linking Policy — attribution requirements for review snippets
• API Access and Limits — this endpoint has a separate allowance