Skip to content
API reference/
/
Get cities for activity

Musement API (3.5.0)

For merchant or affiliate partners wishing to use the Musement API.

Find out more about Musement API

Authentication

See the Authentication section for details on how to authenticate with the API.

Release notes

2024-06-18

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Changed default min_buy value from -1 to 1

2024-02-21

Endpoints

  • Added GET /orders/{orderUuid}/refunds
    • Returns an array of paid refunds for an order

2024-02-20

Endpoints

  • GET /activities/{activityUuid}/dates/{date}
    • Added availability, max_buy and min_buy properties to timeslots. For more info, check out our guide
Download OpenAPI description
openapi.json
openapi.yaml
Overview
API distribution team
api-distribution@tui.com
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://partner-api.musement.com/_mock/reference/openapi
Sandbox server
https://sandbox.musement.com/api/v3
Production server
https://api.musement.com/api/v3

Searching activities

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

Operations

Activity info

A collection of endpoints which can be used to provide information to customers about a specific activity.

Operations

Get country for activity

Request

Returns the country associated with the activity's default city.

Path
activityUuidstring(uuid)required

The UUID of the activity.

Headers
Accept-Languagestring(Language code)

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

Default en-US
X-Musement-Applicationstring(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-Versionstring^[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.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/country' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Country for activity

Bodyapplication/json
country_prefixstring

The country's main telephone country code.

Example: "+39"
currency_codestring= 3 characters

The main currency for the country as a Musement currency code. For a complete list of currencies, refer to the /currencies endpoint.

Example: "EUR"
iso_codestring= 2 charactersrequired

The two-character ISO code for the country.

Example: "IT"
iso3charstring= 3 charactersrequired

The three-character ISO code for the country.

Example: "ITA"
namestringrequired

The country's name, translated based on the Accept-Language header value.

Example: "Italy"
idintegerDeprecatedrequired

The country's numeric ID. This property will be removed in the future.

Example: 82
Response
application/json
{
  "country_prefix": "+39",
  "currency_code": "EUR",
  "id": 82,
  "iso_code": "IT",
  "iso3char": "ITA",
  "name": "Italy"
}

Get cities for activity

Request

Every activity has one default city which appears in the /activities and /activities/{activityUuid} endpoints. However, an activity may be connected to multiple cities.

This endpoint lists all connected cities and indicates which one is the default.

For more info, check out our guide.
Path
activityUuidstring(uuid)required

The UUID of the activity.

Headers
Accept-Languagestring(Language code)

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

Default en-US
X-Musement-Applicationstring(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-Versionstring^[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.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/destinations' \
  -H 'Accept-Language: en-US' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Cities for activity

Bodyapplication/jsonArray [
activities_countinteger

The number of available activities for the city.

Example: 14
idinteger>= 1

The city's numeric ID.

Example: 76
codestring

A string identifier for the city, based on the English version of the city name. This property is not affected by the Accept-Language header.

Example: "washington dc"
contentstring

A plain text description of the city, translated according to the Accept-Language header value.

Example: "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_htmlstring

A description of the city with HTML tags, translated according to the Accept-Language header value.

Example: "<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>"
countryobject(Country)
Example: {"id":184,"iso_code":"US","iso3char":"USA","name":"United States of America"}
cover_image_urlstring(uri)

A URL for the city's cover image.

Example: "https://images-sandbox.musement.com/cover/0001/43/washington_header-42349.jpeg"
event_countinteger

The number of available activities for the city.

headlinestring

An SEO-friendly version of the city name for a page headline, translated based on the Accept-Language header value.

latitudenumber(float)
Example: 38.918
longitudenumber(float)
Example: -77.037
list_countinteger

The number of available Musement list pages for the city.

meta_descriptionstring

An SEO-friendly description of the city, translated based on the Accept-Language header value.

Example: "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."
meta_titlestring

An SEO-friendly version of the city name, translated based on the Accept-Language header value.

namestring

The name of city, translated according to the Accept-Language header value.

Example: "Washington DC"
slugstring

The city slug, used for creating the city URL. Changes based on the value of the Accept-Language value.

time_zonestring

The city's time zone.

Example: "America/New_York"
Based on PHP's list of valid time zones.
topboolean

When true, the city is considered one of Musement's most popular cities.

Default false
urlstring(uri)

An automatically generated Musement URL for the city based on the X-Musement-Market header and slug property. The URL is only valid for select X-Musement-Market values and cities.

Example: "https://.sbox.musement.com/us/washington-dc/"
uuidstring(uuid)

The city's UUID.

Example: "ec1dd48e-339d-11ea-ba3c-029a16533fe4"
venue_countinteger

The number of available venues in the city.

Example: 1
weightinteger

A property used for ranking multiple cities by popularity. Top selling cities will have a higher value.

Example: 2
defaultbooleanrequired

The default city for an activity always appears in the /activities and /activities/{activityUuid} endpoints.

Example: true
morestringDeprecated

Additional information about the city in plain text, ideal for a "Read more" section, translated based on the Accept-Language header value.

more_htmlstringDeprecated

Additional information about the city with HTML tags, ideal for a "Read more" section, translated based on the Accept-Language header value.

]
Response
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": { … },
    "cover_image_url": "https://images-sandbox.musement.com/cover/0001/43/washington_header-42349.jpeg",
    "activities_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,
    "url": "https://.sbox.musement.com/us/washington-dc/",
    "uuid": "ec1dd48e-339d-11ea-ba3c-029a16533fe4",
    "venue_count": 1,
    "weight": 2,
    "default": true
  }
]

Get extra customer data schema for activity

Request

Extra customer data is information requested per reservation. You can use this endpoint for a preview of possible fields that might be used during the reservation flow.

The response follows the JSON Schema Specification to describe the info requested for each participant.

For more info, check out our guide.
Path
activityUuidstring(uuid)required

The UUID of the activity.

Headers
X-Musement-Applicationstring(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-Versionstring^[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.
curl -i -X GET \
  'https://partner-api.musement.com/_mock/reference/openapi/activities/{activityUuid}/extra-customer-data/schema' \
  -H 'X-Musement-Application: string' \
  -H 'X-Musement-Version: 3.4.0'

Responses

Extra customer data for activity

Bodyapplication/json
titlestringrequired

The type of item:

  • cart_customer_guest: Customer info for cart
  • cart_item_participants_info: Participant info for cart item
  • form: Extra customer data
  • participant: Participant info
Enum"cart_customer_guest""cart_item_participants_info""form""participant"
Example: "form"
typestringrequired
Value"object"
Example: "object"
propertiesobjectrequired
Example: {"phone_number":{"type":"string","title":"Phone number","propertyOrder":1}}
properties.​property name*objectadditional property

Each property varies depending on the activity configuration.

requiredArray of stringsrequired

A list of properties which require values in order to complete a reservation.

Example: ["phone_number"]
Response
application/json
{
  "title": "form",
  "type": "object",
  "properties": {
    "property1": { … },
    "property2": { … },
    "phone_number": { … }
  },
  "required": [
    "phone_number"
  ]
}

Pickups

Some activities require selecting a pickup location as part of the booking flow.

Operations

Dates

A collection of endpoints for selecting available dates and products.

Operations

Carts

A collection of endpoints for managing a customer's cart during the booking flow.

Operations

Customer info

When making a reservation, different steps must be taken to provide information about the customers. This collection includes endpoints for submitting info about the lead booker, extra customer data and participant info.

Operations

Orders

A collection of endpoints for managing orders as part of the booking flow.

Operations

Payments

A collection of endpoints regarding payment during the booking flow. Partners have multiple payment options at their disposal, depending on agreements with the Strategic partnerships team.

Operations

Cancellations

It is possible to cancel reservations, provided that the activity in question is refundable.

Operations

Activities

Activities can be any tour, attraction or experience that customers can reserve via the Musement API.

Operations

Categories

Categories group activities based on similar characteristics.

Operations

Cities

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

Operations

Countries

A collection of endpoints related to countries in the Musement catalog.

Operations

Lists

Lists are collections of Musement activities and third-party destinations grouped together based on editorial themes.

Operations

Venues

Venues are popular attractions or landmarks.

Operations

Additional searches

A collection of additional endpoints which can be used to search parts of the catalog.

Operations

Carts

A collection of cart endpoints which are not strictly necessary for the booking flow.

Operations

Metadata

Metadata is used for configuring several activity properties.

Operations

Reviews

Customers may leave reviews about their experience with an activity. Reviews consist of a numeric rating and optional written comment.

Operations

Vouchers

A collection of endpoints to use at the end of the booking flow to retrieve reserved tickets and vouchers.

Operations

Webhooks

A collection of webhook requests that Musement's API can make to a partner's service.

Webhooks

Activities

A collection of deprecated endpoints for activities.

Operations

Carts

A collection of deprecated endpoints for carts.

Operations

Cities

A collection of deprecated endpoints for cities.

Operations

Verticals

Verticals are a type of macro category which group various parts of the catalog together based on similar characteristics.

They are considered deprecated.

Operations

Cities

A collection of endpoints for cities that were removed from the API.

Operations

Countries

A collection of endpoints for countries that were removed from the API.

Operations

Events

A collection of endpoints for events, an older term for activities, that were removed from the API.

Operations

Misc

A collection of various endpoints that were removed from the API.

Operations

Venues

A collection of endpoints for venues that were removed from the API.

Operations
Copyright © TUI Musement. All rights reserved.