Searching activities

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

Search activities

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
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
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
discounted
string

Filter results by discount:

  • NO: return activities without discounts.
  • YES: only return activities with discounts.
Enum: NO YES
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 YES NO
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
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 ten 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: up to 1000 hotels
  • 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 category categories_tree city country duration feature hotel 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
text
string

Filter results by key words.

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
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
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: NONE ALL
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.

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.

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
Responses
200

Activities

default

Error

get/activities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/activities?available_from=2019-08-24&available_language_in=en%2Cit&available_to=2019-08-24&category_in=new-activities&city_in=0&coordinates=45.7386%2C-9.3641&country_in=IT%2CUS&default_price_range=0%2C34.23&distance=5KM&discounted=NO&duration_range=2%2C8&extend_content_fields=AUTO&extend_other_languages=AUTO&feature_in=free%2Cskip&fuzziness_level=AUTO&include_facets=feature%2Cservice&limit=10&offset=0&pickup_in=497f6eca-6276-4993-bfeb-53cbbbba6f08&preferred_seller_boost=1000&preferred_seller_code=Direct&seller_in=Direct&text=string&text_operator=AND&service_in=pick-up%2Cpet-friendly&sort_by=price%2C-rating&temporary=NO&venue_in=0&vertical_in=sightseeing&zero_terms_query=NONE' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
{
  • "data": [
    ],
  • "facets": [
    ],
  • "meta": {
    }
}

Search activities in category

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.

offset
integer >= 0
Default: 0

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

limit
number <= 100
Default: 100

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

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-city relevance-external relevance
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.

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.

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
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

get/categories/{categoryId}/activities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/categories/{categoryId}/activities?city=1&offset=0&limit=100&sort_by=city-relevance&venue=1&vertical=1' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[
  • {
    }
]

Search activities in city

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-city relevance-external relevance
header Parameters
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.

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.

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.

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
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

get/cities/{cityId}/activities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/activities?available_from=2019-08-24&available_to=2019-08-24&category=1&limit=100&offset=0&sort_by=city-relevance' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[
  • {
    }
]

Search activities in country

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.

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.

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
Responses
200

Activities in country

400

Bad request: there are errors in the request

401

Unauthorized: token is not valid

404

Resource not found

503

Service unavailable

get/countries/{countryId}/activities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/countries/{countryId}/activities?limit=10&offset=0&priority_city=1&vertical=1' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[
  • {
    }
]

Search activities in venue

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-city relevance-external relevance
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.

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
Responses
200

Activities in venue

302

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

401

Unauthorized: token is not valid

404

Resource not found

503

Service unavailable

get/venues/{venueId}/activities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/venues/{venueId}/activities?category=1&city=1&flavour=1&limit=100&offset=0&sort_by=city-relevance&vertical=1' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Currency: USD' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[
  • {
    }
]