# 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. p In the example below, the response will return activities with the *Museums* category (code `new-museums`): ```bash 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](/api/catalog/categories). ## 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: ```bash 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](/api/catalog/activities/cities). ## 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: ```bash 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. p In the example below, the response will return activities that take place in Italy (ISO code `IT`): ```bash 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: ```bash 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](/api/catalog/activities/types/open-date) are valid for at least one date in the date range before they expire. ## Features *Features*, like [services](#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. p The example below returns activities that are tagged as either skip-the-line (`skip`) or free for children (`ADDVA_KIDS`): ```bash 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](/api/catalog/activities/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. p The `flavour_not_in` query parameter *excludes* activities which use any of the specified flavours. p 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`): ```bash 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: ```bash 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: ```bash 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. ```bash 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](/api/getting-started/headers/currency). ## Services *Services*, like [features](#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. p The example below returns activities that are tagged as either providing an audio guide (`audioguide`) or being pet friendly (`pet-friendly`): ```bash 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*: ```bash 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](/api/catalog/activities/venues).