Searching activities

A collection of endpoints which can be used to search the catalog for relevant activities.

Search activities

get/activities

Returns an array of activities and additional meta information.

Request
query Parameters
available_from
string <date>

Filter activities by their available dates. Only activities with at least one available date after this parameter value are returned.

Must be used together with available_to parameter.

available_language_in
Array of strings (Language code)

Filter activities to those which accommodate at least one of the specified languages.

Example: available_language_in=en,it
available_to
string <date>

Filter activities by their available dates. Only activities with at least one available date before this parameter value are returned.

Must be used together with available_from parameter.

category_in
Array of strings (Category code)

Filter results to those which use at least one of the specified categories.

Example: category_in=new-activities
city_in
Array of integers (City ID)

Filter results to those which are connected to at least one of the specified cities.

coordinates
string(-)?\d{1,3}(\.\d+)?,(-)?\d{1,3}(\.\d+)?

Filter results to those located near the specified latitude and longitude. Separate the coordinates with a comma.

Must be used together with the distance parameter.

Example: coordinates=45.7386,-9.3641
For more info, check out our guide.
country_in
Array of strings (Country ISO code)

Filter results to those which are connected to at least one of the specified countries.

Example: country_in=IT,US
default_price_range
string^\d{1,5}(.\d{1,2})?,\d{1,5}(.\d{1,2})?$

Filter results by price. Results will contain pricing which falls between the two specified amounts.

Parameter requires two values, a lower and upper bound, separated by a comma. Each value must be a float or integer. Parameter accepts up to two decimal digits.

This parameter uses the currency value in the X-Musement-Currency header.

Example: default_price_range=0,34.23
discounted
string

Filter results by discount:

  • NO: return activities without discounts.
  • YES: only return activities with discounts.
Enum: NO YES
distance
string^\d{1,1000}(KM|M)$

Filter results to activities located within the specified radius around a pair of coordinates. Parameter must include one of the following units:

  • KM: kilometers
  • M: miles

Must be used together with the coordinates parameter.

Example: distance=5KM
For more info, check out our guide.
duration_range
string^\d{1,5}(.\d{1,2})?(,\d{1,5}(.\d{1,2})?)?$

Filter results by their duration. Parameter can accept a single lower bound value or both a lower and upper bound separated by a comma.

Parameter values are treated as hours. Values can have up to two decimal places.

Example: duration_range=2,8
extend_content_fields
string
Default: AUTO

Combined with the text parameter, filter results based on the title only or all content properties:

  • AUTO: initially filter results based on titles. If no results are found, extend the search to include other content properties.
  • NO: filter results based on titles only.
  • YES: filter results based on all content properties.
Enum: AUTO NO YES
extend_other_languages
string
Default: AUTO

Combined with the text parameter, filter results based on the Accept-Language header value or all languages:

  • AUTO: initially filter results based on the Accept-Language header value. If no results are found, extend the search to include all languages.
  • NO: filter results based on the Accept-Language header value.
  • YES: filter results based on all languages.
Enum: AUTO NO YES
feature_in
Array of strings (Feature code)

Filter results to activities which use at least one of the specified features.

Example: feature_in=free,skip
flavour_in
Array of integers (Flavour ID)

Filter activities to those which use at least one of the specified flavours.

Flavours are available from the GET /flavours endpoint.

flavour_not_in
Array of integers (Flavour ID)

Filter activities to exclude those which use any of the specified flavours.

Flavours are available from the GET /flavours endpoint.

fuzziness_level
string
Default: LEVEL-0

Change the "fuzziness" level for the text parameter value. Higher levels are less strict about exact text matches.

Enum: AUTO LEVEL-0 LEVEL-1 LEVEL-2
include_facets
Array of strings

Include specified statistics about activities matching the query. Results appear in the facets property in the response.

Every facet contains details which can be used to modify the /activities query parameters further.

Most facets contain a breakdown of the number of activities which use that value. These numbers account for all activities which match the query, not just those in the response. When querying for prices, facet values contain the relevant price value instead.

Valid parameter values provide:

  • available_language: up to ten languages
  • category: up to ten categories
  • categories_tree: all categories in their tree structure
  • city: up to ten cities
  • country: up to 1000 countries
  • duration: a breakdown of activity durations:
    • Up to 2 hours
    • 2-4 hours
    • 4-8 hours
    • 8-24 hours
    • Over 24 hours
  • feature: up to 10 features
  • hotel: deprecated, use pickup or hotel_pickup instead
  • hotel_pickup: up to 1000 pickup points (type HOTEL)
  • meeting_point_pickup: up to 1000 pickup points (type PICKUP)
  • pickup: up to 1000 pickup points (of any type)
  • price: lowest and highest prices
  • seller: up to 10 seller gateways
  • service: up to 10 services
  • vertical: up to 10 verticals
  • vertical_categories: up to 10 verticals
Items Enum: available_language categories_tree category city country duration feature hotel hotel_pickup meeting_point_pickup pickup price seller service venue vertical vertical_categories
Example: include_facets=feature,service
limit
integer <= 100
Default: 10

Limit the maximum number of results to include in the response.

offset
integer >= 0
Default: 0

Exclude the first N results from the response, where N is the specified integer value.

pickup_in
Array of strings <uuid> (Pickup UUID)

Filter results to activities which use at least one of the specified pickups.

preferred_seller_boost
integer
Default: 1000

A numeric value to increase the boost for activities whose seller gateway matches the preferred_seller_code parameter.

preferred_seller_code
string (Seller gateway code)

Activities connected to the specified seller gateway are "boosted" - treated as if they have a higher relevance value. When sorting by -relevance (from highest to lowest), these activities are more likely to appear first.

Example: preferred_seller_code=Direct
seller_in
Array of strings (Seller gateway code)

Filter results to activities which use any of the specified seller gateways.

Example: seller_in=Direct
service_in
Array of strings (Service code)

Filter results to activities which use at least one of the specified services.

Example: service_in=pick-up,pet-friendly
sort_by
Array of strings

Sort results by one or more criteria.

Results are sorted from lowest to highest value by default. To sort from highest to lowest, add - in front of the value.

Sorting by distance requires the coordinates parameter.

Items Enum: -distance -price -rating -relevance -relevance-category -relevance-city -relevance-external -relevance-venue distance price rating relevance relevance-category relevance-city relevance-external relevance-venue
Example: sort_by=price,-rating
temporary
string

Filter results based on their temporary property:

  • NO: return results with a temporary value of false.
  • YES: return results with a temporary value of true.
Enum: NO YES
text
string

Filter results by key words.

For more info, check out our guide.
text_operator
string
Default: AUTO

Change how the text parameter filters results when multiple words are used:

  • AND: results must contain all the key words.
  • AUTO: filters by AND first. If there are no results, extend to include OR results.
  • OR: results must contain at least one of the key words.
Enum: AND AUTO OR
venue_in
Array of integers (Venue ID)

Filter results to activities which are connected to at least one of the specified venues.

vertical_in
Array of strings (Vertical code)
Deprecated

Filter results to those which are connected to at least one of the specified verticals.

Example: vertical_in=sightseeing
zero_terms_query
string
Default: NONE

If set to ALL, if all of the stop words have been removed, search will be performed, if set to 'NONE' will not

Enum: ALL NONE
header Parameters
Accept-Language
string (Language code)
Default: en-US

The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.

X-Musement-Application
string (Application value)

A partner's application value, used for analyzing API usage and to identify areas of improvement.

For more info, check out our guide.
X-Musement-Currency
string (Currency code)
Default: USD

A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.

X-Musement-Market
string (Musement market)
Default: us

Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.

An invalid X-Musement-Market value will return a 400 status code response.

For more info, check out our guide.
X-Musement-Version
string^[0-9]+?.[0-9]+?.[0-9]+?$

The API version to use for the request.

When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.

Example: 3.4.0
For more info, check out our guide.
Responses
200

Activities

default

Error

Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "facets": [
    ],
  • "meta": {
    }
}
Search activities in category
get/categories/{categoryId}/activities
Response only contains activities with a status of ONLINE.


Request 
path Parameters
categoryId
required
integer (Category ID)   >= 1 
The numeric ID of the category.


 
query Parameters
city
integer (City ID)   >= 1 
The numeric ID of the city.


 
limit
number  <= 100 
 Default:  100
Limit the maximum number of results to include in the response.


 
offset
integer  >= 0 
 Default:  0
Exclude the first N results from the response, where N is the specified integer value.


 
sort_by
string
 Default:  city-relevance
Sort results by specific properties. Most values sort activities from highest to lowest values. However, when sorting by price, the results appear from lowest to highest values.


 Enum: city-relevance external-relevance price rating relevance relevance-city relevance-external  
venue
integer (Venue ID)   >= 1 
The numeric ID of the venue.


 
vertical
integer (Vertical ID)   >= 1 
 Deprecated 
The numeric ID of the vertical.


 
header Parameters
Accept-Language
string (Language code) 
 Default:  en-US
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.


 
X-Musement-Application
string (Application value) 
A partner's application value, used for analyzing API usage and to identify areas of improvement.


 
For more info, check out our guide.
X-Musement-Currency
string (Currency code) 
 Default:  USD
A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.


 
X-Musement-Market
string (Musement market) 
 Default:  us
Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.


An invalid X-Musement-Market value will return a 400 status code response.


 
For more info, check out our guide.
X-Musement-Version
string^[0-9]+?.[0-9]+?.[0-9]+?$
The API version to use for the request.


When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.


 
 Example:  3.4.0
For more info, check out our guide.
Responses 
200
Activities in category


302
Found: when the limit parameter is greater than the maximum, the endpoint is redirected with limit={maximum}


404
Resource not found


default
Error


Request samples 
Response samples 
application/json
[
  • {
    }
]
Search activities in city
get/cities/{cityId}/activities
Returns a list of available activities for the city. If no date range is specified with the available_from and available_to parameters, a default of one year is used.


Request 
path Parameters
cityId
required
integer (City ID)   >= 1 
The numeric ID of the city.


 
query Parameters
available_from
string <date> 
Filter activities by their available dates. Only activities with at least one available date after this parameter value are returned.


Must be used together with available_to parameter.


 
available_to
string <date> 
Filter activities by their available dates. Only activities with at least one available date before this parameter value are returned.


Must be used together with available_from parameter.


 
category
integer (Category ID)   >= 1 
Filter results by category.


 
limit
integer  <= 100 
 Default:  100
Limit the maximum number of results to include in the response.


 
offset
integer  >= 0 
 Default:  0
Exclude the first N results from the response, where N is the specified integer value.


 
sort_by
string
 Default:  city-relevance
Sort results by specific properties. Most values sort activities from highest to lowest values. However when sorting by price, the results appear from lowest to highest values.


 Enum: city-relevance external-relevance price rating relevance relevance-city relevance-external  
header Parameters
Accept-Language
string (Language code) 
 Default:  en-US
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.


 
X-Musement-Application
string (Application value) 
A partner's application value, used for analyzing API usage and to identify areas of improvement.


 
For more info, check out our guide.
X-Musement-Currency
string (Currency code) 
 Default:  USD
A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.


 
X-Musement-Market
string (Musement market) 
 Default:  us
Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.


An invalid X-Musement-Market value will return a 400 status code response.


 
For more info, check out our guide.
X-Musement-Version
string^[0-9]+?.[0-9]+?.[0-9]+?$
The API version to use for the request.


When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.


 
 Example:  3.4.0
For more info, check out our guide.
Responses 
200
Activities in city


302
When the limit parameter is greater than the maximum, endpoint is redirected with limit={maximum}.


404
Resource not found


default
Error


Request samples 
Response samples 
application/json
[
  • {
    }
]
Search activities in country
get/countries/{countryId}/activities
Response only contains activities with a status of ONLINE.


Request 
path Parameters
countryId
required
integer (Country ID) 
The country's numeric ID.


 
query Parameters
limit
integer  <= 100 
 Default:  10
Limit the maximum number of results to include in the response.


Using a value greater than the maximum is ignored and the maximum number of possible results is used instead.


 
offset
integer  >= 0 
 Default:  0
Exclude the first N results from the response, where N is the specified integer value.


 
priority_city
integer (City ID)   >= 1 
Sort results so that activities which belong to the requested city appear first.


Returns a 400 status code response if the city does not belong to the country.


 
vertical
integer (Vertical ID)   >= 1 
 Deprecated 
The numeric ID of the vertical.


 
header Parameters
Accept-Language
string (Language code) 
 Default:  en-US
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.


 
X-Musement-Application
string (Application value) 
A partner's application value, used for analyzing API usage and to identify areas of improvement.


 
For more info, check out our guide.
X-Musement-Currency
string (Currency code) 
 Default:  USD
A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.


 
X-Musement-Market
string (Musement market) 
 Default:  us
Musement markets contain a modified catalog of activities and prices. Partners are expected to use their assigned market code to view their customized catalog.


An invalid X-Musement-Market value will return a 400 status code response.


 
For more info, check out our guide.
X-Musement-Version
string^[0-9]+?.[0-9]+?.[0-9]+?$
The API version to use for the request.


When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.


 
 Example:  3.4.0
For more info, check out our guide.
Responses 
200
Activities in country


404
Resource not found


default
Error


Request samples 
Response samples 
application/json
[
  • {
    }
]
Search activities in venue
get/venues/{venueId}/activities
Response only contains activities with a status of ONLINE.


Request 
path Parameters
venueId
required
integer
Numeric ID for venue


 
query Parameters
category
integer (Category ID)   >= 1 
Filter results by category.


 
city
integer (City ID)   >= 1 
The numeric ID of the city.


 
flavour
integer  >= 1 
Filter results by flavour. Parameter expects a single flavour ID.


 
limit
integer  <= 100 
 Default:  100
Limit the maximum number of results to include in the response.


 
offset
integer  >= 0 
 Default:  0
Exclude the first N results from the response, where N is the specified integer value.


 
sort_by
string
 Default:  city-relevance
Sort results by specific properties. Most values sort activities from highest to lowest values. However, when sorting by price, the results appear from lowest to highest values.


 Enum: city-relevance external-relevance price rating relevance relevance-city relevance-external  
vertical
integer (Vertical ID)   >= 1 
 Deprecated 
The numeric ID of the vertical.


 
header Parameters
Accept-Language
string (Language code) 
 Default:  en-US
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.


 
X-Musement-Application
string (Application value) 
A partner's application value, used for analyzing API usage and to identify areas of improvement.


 
For more info, check out our guide.
X-Musement-Currency
string (Currency code) 
 Default:  USD
A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.


 
X-Musement-Version
string^[0-9]+?.[0-9]+?.[0-9]+?$
The API version to use for the request.


When absent, the latest version is used by default, however the latest version may not be stable. Partners are encouraged to use the latest stable version: 3.4.0.


 
 Example:  3.4.0
For more info, check out our guide.
Responses 
200
Activities in venue


302
Found: when the limit parameter is greater than the maximum, the endpoint is redirected with limit={maximum}


404
Resource not found


default
Error


Request samples 
Response samples 
application/json
[
  • {
    }
]