Cities

Cities are different types of destinations: islands, natural landmarks, beaches, actual cities and more.

Search cities

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

Filter and sort results to cities closest to a provided latitude and longitude point.

distance
string\d+

Filter results to cities that are within the specified distance (in KM) around a provided pair of coordinates.

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.

prioritized_country
integer (Country ID) >= 1

Sort results so that cities which belong to the specified country appear first.

prioritized_country_cities_limit
integer >= 1

Limit the number of cities in the results which belong to the specified prioritized_country.

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

Cities

404

Not found: no city matches request parameters

default

Error

get/cities
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities?coordinates=string&distance=string&limit=10&offset=0&prioritized_country=1&prioritized_country_cities_limit=1' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[
  • {
    }
]

Get city

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

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

City

404

Resource not found

default

Error

get/cities/{cityId}
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
{
  • "id": 76,
  • "code": "washington dc",
  • "content": "Often overshadowed by the more flashy New York City, Washington DC represents an essential destination of an East Coast tour. In fact, the District of Columbia is a real must-see for those who want to discover and get in touch with the true essence of American history and culture. Not only a political capital but also an important cultural and artistic center, Washington DC is found between the states of Virginia - on its southwest side - and Maryland - on its southeast, northeast, and northwest sides. The ideal tour of Washington starts from the National Mall, a monumental avenue of about 3 km that runs along the east-west from Capitol Hill to the Lincoln Memorial.",
  • "content_html": "<p>Often overshadowed by the more flashy New York City, <strong>Washington DC </strong>represents an essential destination of an East Coast tour. In fact, the <strong>District of Columbia</strong> is a real <strong>must-see</strong> for those who want to discover and get in touch with the true essence of American history and culture.</p><p>Not only a <strong>political capital</strong> but also an <strong>important cultural and artistic center</strong>, Washington DC is found between the states of Virginia - on its southwest side - and Maryland - on its southeast, northeast, and northwest sides.</p><p>The ideal tour of Washington starts from the <strong>National Mall</strong>, a monumental avenue of about 3 km that runs along the east-west from <strong>Capitol Hill</strong> to the <strong>Lincoln Memorial</strong>. </p>",
  • "country": {
    },
  • "event_count": 14,
  • "latitude": 38.918,
  • "list_count": 0,
  • "longitude": -77.037,
  • "meta_description": "Find out what's happening in Washington D.C. and book your tickets for the best museums and operas in advance. Skip the line, make your trip more enjoyable. Museums, opera, classical concerts at your fingertips.",
  • "more": "",
  • "name": "Washington DC",
  • "show_in_popular": false,
  • "time_zone": "America/New_York",
  • "top": false,
  • "uuid": "ec1dd48e-339d-11ea-ba3c-029a16533fe4",
  • "venue_count": 1,
  • "weight": 2
}

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
[
  • {
    }
]

Get activities available today in city

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

query Parameters
limit
integer [ 1 .. 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.

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 available today in city

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/cities/{cityId}/activities/today
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/activities/today?limit=100&offset=0' \
  -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
[
  • {
    }
]

Get activities available tomorrow in city

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

query Parameters
limit
integer [ 1 .. 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.

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 available tomorrow in city

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/cities/{cityId}/activities/tomorrow
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/activities/tomorrow?limit=100&offset=0' \
  -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
[
  • {
    }
]

Get categories for city

Results are categories with activities that have a status of ONLINE.

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

query Parameters
limit
integer [ 0 .. 50 ]
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.

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

Categories for city

404

Resource not found

default

Error

get/cities/{cityId}/categories
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/categories?limit=10' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[]

Get category with city

This endpoint returns a category along with the requested city in the city property, useful when constructing a page for a category in a city.

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

categoryId
required
integer (Category ID) >= 1

The numeric ID of the category.

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

Category with city

404

Resource not found

default

Error

get/cities/{cityId}/categories/{categoryId}
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/categories/{categoryId}' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
{}

Search lists in city

Response only contains published lists with one or more available items.

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

query Parameters
exclude_not_tagged
string

Exclude results which have no tags.

Enum: NO YES
limit
integer <= 100
Default: 100

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

listtags
Array of strings (List tag)

Filter results to those which best match the specified list tags.

listtype
Array of integers (List type ID)

Filter results to those which match any of the specified list types.

offset
integer >= 0
Default: 0

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

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-Device-Type
string

This header affects the results of the /lists and /cities/{cityId}/lists endpoints. The response will contain lists which are considered better for customers using the specified device type.

Enum: DESKTOP MOBILE
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

Lists

404

Not found: no list matches request parameters

default

Error

get/cities/{cityId}/lists
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/lists?exclude_not_tagged=NO&limit=100&listtags=string&listtype=0&offset=0&vertical=1' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Device-Type: DESKTOP' \
  -H 'X-Musement-Market: us' \
  -H 'X-Musement-Version: 3.4.0'
Response samples
application/json
[]

Get venues in city

Response only contains venues with a status of ACTIVE and events_count value greater than zero.

Request
path Parameters
cityId
required
integer (City ID) >= 1

The numeric ID of the city.

query Parameters
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.

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

Venues in city

404

Resource not found

default

Error

get/cities/{cityId}/venues
Request samples
curl -i -X GET \
  'https://sandbox.musement.com/api/v3/cities/{cityId}/venues?limit=10&offset=0&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
[
  • {
    }
]