Get Recommended Destinations

Tool

getRecommendedDestinations

Description

Retrieve the best travel destinations (cities) worldwide based on user interests and preferences.

This tool supports filtering by interests, traveler type, trip context, price range, currency, and geographic scope (country or continent filters). Results are tailored to match the provided criteria.

Unlike activity recommendation tools that require a specific location, this tool performs global destination discovery and returns destination cities with relevant activities.

How It Works:

• Required Input:

  At least one value in interests is required.

• Global Discovery:

  Location parameters such as latitude, longitude, city name, or IATA code are not required.

• Geographic Filtering:

  You can narrow recommendations using country or continent filters.

  • includeCountryCodes and excludeCountryCodes use ISO 3166-1 alpha-2 country codes.

  • includeContinentCodes and excludeContinentCodes use continent codes (for example EU, AS, NA).

  • If any country code filter is provided, continent code filters are ignored.

• Personalization Signals:

  Recommendation scoring prioritizes interests and ratings, and dynamically applies additional weighting when optional dimensions are provided:

  • Price weighting when minPrice or maxPrice is provided

  • Traveler type weighting when travelerType is provided

  • Trip context weighting when tripContext is provided

• Standalone Usage Rule:

  This is a standalone destination discovery tool. Do not automatically chain it with getRecommendedActivities. Only call activity recommendations afterwards if the user explicitly asks for more activities in a specific destination.

Example Request:

{
  "maxDestinations": 5,
  "interests": ["snorkeling", "nightlife"],
  "travelerType": "couple",
  "tripContext": "leisure",
  "minPrice": 20,
  "maxPrice": 180,
  "currencyCode": "EUR",
  "includeContinentCodes": ["EU"],
  "locale": "en-US"
}

Input parameters

Field	Mandatory	Type	Description	Example
maxDestinations	N	integer	Max destinations is the number of destination cities returned by the API. It is optional and must be a positive integer between 1 and 10. Default is 5.	5
interests	Y	array of strings	The interests parameter is a list of strings that describe what the user wants to do at their destination (for example snorkeling, street food, museums, nightlife, hiking). At least one interest is required to search for matching destinations.	[ “snorkeling”, “nightlife” ]
travelerType	N	string	The travelerType parameter specifies the type of traveler(s) for destination recommendations. Allowed values are: solo, family, couple, group.	couple
tripContext	N	string	The tripContext parameter specifies the purpose of the trip. Allowed values are: business, leisure, staycation. Set this only when the user explicitly expresses trip purpose.	leisure
minPrice	N	number	The minPrice parameter specifies the minimum price for activities at recommended destinations. It must be a positive decimal number.	20
maxPrice	N	number	The maxPrice parameter specifies the maximum price for activities at recommended destinations. It must be a positive decimal number.	150
currencyCode	N	string	The currencyCode parameter specifies the currency for prices using a three-letter ISO 4217 code (for example USD, EUR). If not specified, the API default currency is used.	USD
includeCountryCodes	N	array of strings	Filters destination results to include only specific countries. Values must be ISO 3166-1 alpha-2 country codes.	[ “ES”, “PT” ]
excludeCountryCodes	N	array of strings	Filters destination results to exclude specific countries. Values must be ISO 3166-1 alpha-2 country codes.	[ “US”, “GB” ]
includeContinentCodes	N	array of strings	Filters destination results to include only specific continents. Example values: EU, AS, NA. Ignored when includeCountryCodes or excludeCountryCodes is provided.	[ “EU”, “AS” ]
excludeContinentCodes	N	array of strings	Filters destination results to exclude specific continents. Example values: EU, AS, NA. Ignored when includeCountryCodes or excludeCountryCodes is provided.	[ “NA” ]
locale	N	string	Locale for translated textual content in the response using language-region format (for example en-US, fr-FR, es-ES).	en-US
externalClientId	N	string	Optional technical identifier used to associate recommendations with a specific client or agent for tracking.	agent-12345

Output sample

Response Body

{
  "destinations": [
    {
      "cityName": "Palma de Mallorca",
      "countryCode": "ES",
      "continentCode": "EU",
      "relevanceScore": 0.89,
      "activities": [
        {
          "title": "Sunset Catamaran Cruise",
          "minPrice": 75,
          "currency": "EUR"
        },
        {
          "title": "Snorkeling in Cala Formentor",
          "minPrice": 45,
          "currency": "EUR"
        }
      ]
    }
  ]
}