Searching for activities

You can find all of our available activities via a single endpoint: /activities

However, most people don't have the patience to look through thousands of entries to find what they want. Filters help reduce results down to the activities that are more likely to interest customers. You can filter activities in the catalog by some of the more popular search topics: categories, cities, countries, coordinates, dates, prices and venues.

Categories

Use the category_in parameter to get activities that use at least one of the categories in the query. This parameter requires a comma-separated list of one or more category codes, not category IDs.

In the example below, the response will return activities with the Museums category (code new-museums):
Copy
Copied
curl -X GET '{baseUrl}/activities?category_in=new-museums' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

For more information about categories, check out the category guide.

Cities

Cities in the Musement API can refer to different types of destinations. This includes islands, natural landmarks, beaches, actual cities and more.

You can use the city_in parameter to get activities that take place in any of the cities in the query. To specify multiple cities, separate their IDs with commas.

In the example below, the response will return activities that take place in Genoa or Reykjavik:

Copy
Copied
curl -X GET '{baseUrl}/activities?city_in=13,193' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

For more information about cities, check out the dedicated section.

Coordinates

You can filter available activities located around a specific set of coordinates. This query requires two parameters:

  • coordinates: The latitude and longitude separated by a comma.
  • distance: The radius around the coordinates to search. You must specify the unit of measure: miles (M) or kilometers (KM).

The following example provides all available activities in a five-kilometer radius around a set of coordinates in Milan:

Copy
Copied
curl -X GET '{baseUrl}/activities?coordinates=45.459,9.183&distance=5KM' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Countries

You can use the country_in parameter to get activities that take place in any of the countries in the query. Note that this parameter requires a comma-separated list of one or more country ISO codes, not country IDs.

In the example below, the response will return activities that take place in Italy (ISO code IT):
Copy
Copied
curl -X GET '{baseUrl}/activities?country_in=IT' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Dates

By default, the activities returned will be available for at least one date for the next 365 days. You can filter results to a narrower date range by adding the available_from and available_to parameters. Both parameters must be used together:
Copy
Copied
curl -X GET '{baseUrl}/activities?available_from={startDate}&available_to={endDate}' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Resulting calendar activities will have at least one available date within the specified date range. Open date activities are valid for at least one date in the date range before they expire.

Features

Features, like services, are a type of tag which indicate special characteristics for an activity. The feature_in query parameter lets you filter results to activities which use at least one of the specified feature tags.

The example below returns activities that are tagged as either skip-the-line (skip) or free for children (ADDVA_KIDS):
Copy
Copied
curl -X GET '{baseUrl}/activities?feature_in=skip,ADDVA_KIDS' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Flavours

Flavours are optional tags which provide more information about an activity. The flavour_in query parameter lets you filter results to activities which use at least one of the specified flavours.

The flavour_not_in query parameter excludes activities which use any of the specified flavours.

To specify multiple flavours in either parameter, separate their IDs with commas.

The example below returns activities that are tagged with either entrance tickets (2) or a guided tour (111), but excludes activities that contain private tours (113):
Copy
Copied
curl -X GET '{baseUrl}/activities?flavour_in=2,111&flavour_not_in=113' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Key words

You can search for key words using the text parameter. Results are activities which contain the key words in any of the following properties:
  • description
  • highlights
  • meta_description
  • title
The example request below returns activities that use the phrase UNESCO World Heritage in the description, highlights, meta_description or title properties:
Copy
Copied
curl -X GET '{baseUrl}/activities?text=UNESCO World Heritage' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

When you use the name of a city or country as a key word, the results are different. You will receive a list of activities which belong to the city or country in your query.

In the example request below, the response will contain activities in the city of Milan:

Copy
Copied
curl -X GET '{baseUrl}/activities?text=Milan' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Prices

You can filter activities by a price range using the default_price_range query parameter. This parameter requires a minimum price and a maximum price, separated by a comma.

In the example below, the response will return all available activities between $9.99 and $100.

Copy
Copied
curl -X GET '{baseUrl}/activities?default_price_range=9.99,100' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Currency: USD' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

To learn more about currencies in responses, check out the currency guide.

Services

Services, like features, are a type of tag which indicate special characteristics for an activity. The service_in query parameter lets you filter results to activities which use at least one of the specified service tags.

The example below returns activities that are tagged as either providing an audio guide (audioguide) or being pet friendly (pet-friendly):
Copy
Copied
curl -X GET '{baseUrl}/activities?service_in=audioguide,pet-friendly' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Venues

Venues refer to attractions or landmarks. Activities connected to venues may include entrance tickets or the venue may feature prominently as part of the activity.

You can use the venue_in parameter to get activities that take place in any of the venues in the query. To specify multiple venues, separate their IDs with commas.

In the example below, the response will return activities that include the Statue of Liberty:

Copy
Copied
curl -X GET '{baseUrl}/activities?venue_in=411' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

For more information about venues, check out the dedicated section.

Copyright © TUI Musement. All rights reserved.