A collection of endpoints which can be used to search the catalog for relevant activities.
Musement API (3.5.0)
For merchant or affiliate partners wishing to use the Musement API.
See the Authentication section for details on how to authenticate with the API.
GET /activities/{activityUuid}/dates/{date}- Added
availability,max_buyandmin_buyproperties to timeslots. For more info, check out our guide
- Added
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.
A partner's application value, used for analyzing API usage and to identify areas of improvement.
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.
- Mock serverhttps://partner-api.musement.com/_mock/reference/openapi/list-types
- Sandbox serverhttps://sandbox.musement.com/api/v3/list-types
- Production serverhttps://api.musement.com/api/v3/list-types
- curl
- C#
- Node.js
curl -i -X GET \
'https://partner-api.musement.com/_mock/reference/openapi/list-types?limit=10&offset=0' \
-H 'Accept-Language: en-US' \
-H 'X-Musement-Application: string' \
-H 'X-Musement-Version: 3.4.0'[ { "id": 3, "name": "Musement list" } ]
Filter results to those which use at least one of the specified categories.
Filter results to those which are connected to at least one of the specified cities.
Filter results to those which are connected to at least one of the specified countries.
Filter results to those which match any of the specified list types.
Exclude the first N results from the response, where N is the specified integer value.
Filter results based on their temporary property:
NO: return results with a temporary value offalse.YES: return results with a temporary value oftrue.
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.
A partner's application value, used for analyzing API usage and to identify areas of improvement.
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.
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.
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.
- Mock serverhttps://partner-api.musement.com/_mock/reference/openapi/lists
- Sandbox serverhttps://sandbox.musement.com/api/v3/lists
- Production serverhttps://api.musement.com/api/v3/lists
- curl
- C#
- Node.js
curl -i -X GET \
'https://partner-api.musement.com/_mock/reference/openapi/lists?category_in=0&city_in=0&country_in=0&exclude_not_tagged=NO&limit=10&listtags=string&listtype=0&offset=0&temporary=NO&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'Lists
The creators of the list.
A URL for the list's cover image.
A description of the list, translated based on the Accept-Language header value.
The list's items.
A breakdown of the items within the list.
An SEO-friendly description of the list, translated based on the Accept-Language header value.
An SEO-friendly version of the list title to use for search results, translated based on the Accept-Language header value.
The list's subtitle, translated based on the Accept-Language header value.
This property is best used as the page header.
Temporary lists will eventually end and be removed from the /lists endpoint response.
The list's title, translated based on the Accept-Language header value.
This property is best used as a general title to give the page effect. For a page header, please use the subtitle property.
An automatically generated Musement URL for the list based on the X-Musement-Market header and list properties. The URL is only valid for select X-Musement-Market values and lists.
The number of customers who have saved this list to their favorites.
The list's verticals, if any.
A URL for the vertical's cover image.
An SEO-friendly description of the venue, translated based on the Accept-Language header value.
An SEO-friendly version of the venue name, translated based on the Accept-Language header value.
The vertical name, translated based on the Accept-Language header value.
The vertical slug, used for creating the vertical URL. Changes based on the value of the Accept-Language value.
An automatically generated Musement URL for the vertical based on the X-Musement-Market header and slug property. The URL is only valid for select X-Musement-Market values and active verticals.
[ { "id": 244, "subtitle": "Top experiences in New York", "title": "Top experiences", "description": "Pressed for time? Or maybe you just want to know what you can't miss straight up. This list was made for you. It rounds up the best experiences of the city, from fabulous local dining to landmark attractions.", "seo_title": "Top experiences in New York", "seo_description": "Pressed for time? Or maybe you just want to know what you can't miss straight up. This list was made for you. It rounds up the best experiences of the city, from fabulous local dining to attractions.", "temporary": false, "url": "https://.sbox.musement.com/us/new-york/top-experiences-l/", "authors": [ … ], "list_type": { … }, "items": [ … ], "items_count": { … }, "city": { … }, "cover_image_url": "https://images-sandbox.musement.com/default/0001/59/thumb_58199_default_header.jpeg?w=750&h=500", "verticals": [ … ], "category": {} } ]
The value of this parameter might affect the language of the content in the response, provided a translation in the requested language is available.
A partner's application value, used for analyzing API usage and to identify areas of improvement.
A valid currency code from the /currencies endpoint. Default value may vary depending on the X-Musement-Market header value.
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.
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.
- Mock serverhttps://partner-api.musement.com/_mock/reference/openapi/lists/{listId}
- Sandbox serverhttps://sandbox.musement.com/api/v3/lists/{listId}
- Production serverhttps://api.musement.com/api/v3/lists/{listId}
- curl
- C#
- Node.js
curl -i -X GET \
'https://partner-api.musement.com/_mock/reference/openapi/lists/{listId}' \
-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'List
The creators of the list.
A URL for the list's cover image.
A description of the list, translated based on the Accept-Language header value.
The list's items.
An item in a list which represents a Musement activity.
The Musement activity that the item represents.
The main description of the activity. Does not contain HTML. Translated based on the Accept-Language header value.
The main description of the activity in HTML. Translated based on the Accept-Language header value.
The main description of the activity in the Markdown markup language. Translated based on the Accept-Language header value.
Whether any of the content in the response was machine translated or not.
Musement offers the cheapest price available for this activity compared to major competitors.
Describes the reservation flow for the activity:
CALENDAR-NO-TIMESLOTS: Show calendar with dates, but no timeslots.CALENDAR-TIMESLOTS: Show calendar with dates and timeslots.NO-CALENDAR-FIXED-END: Don't show calendar or timeslots. Purchases are valid until a specific date.NO-CALENDAR-FIXED-VALIDITY: Don't show calendar or timeslots. Purchases are valid for a specific number of days.
This property affects activities connected to packages. A voucher is issued for each multiple of the property value.
The categories the activity belongs to.
The lowest price for child options. Only appears for activities connected to certain integrations.
The URL for the activity's cover image.
A time range which will always be unavailable. Dates that fall within the time range do not appear in the /activities/{activityUuid}/dates endpoint.
Values follow the ISO 8601 standard.
When the booking_type property is CALENDAR-NO-TIMESLOTS, the daily property will be true. Ignore this property for all other booking_type values.
Same as the meta_description property.
A discount percentage that might be applied to some (or all) prices in the activity.
A general overview of how long a customer's experience with an activity will last. The min and max properties are both optional. Their presence changes the meaning of the duration:
- When the
minandmaxare both present and equal, this is a single period of time. Example: Lasts 2 hours - When
minandmaxare both present, but different, the activity spans a range of time. Example: Lasts 1 to 2 hours - When
minis absent and `max is present, the minimum duration is unknown. Example: Lasts up to 2 hours - When
minis present andmaxis absent, the maximum duration is unknown. Example: Lasts at least 1 hour - When either
minormaxhas a value ofP0D, the duration cannot be well-defined. Example: Flexible
When the entire duration_range property is absent, use the validity property instead.
When customers are lost or running late, they can use the information in this property to contact the activity provider for help finding the meeting point. Does not contain HTML. Translated based on the Accept-Language header value.
A list of features for the activity and/or reservation flow.
A list of tags about some of the activity's characteristics.
A list of meals the activity includes.
When true, the activity will offer a 100% refund for certin cancellations. Use the /activities/{activityUuid}/refund-policies endpoint for more details.
Whether the activity can be given as a gift on musement.com or not.
The number of green fee days included for activities that take place at golf courses.
The activity is able to accommodate groups of the listed sizes.
Whether the activity requires extra customer data or not.
Whether the activity requires participant info or not.
When true, dates in the /activities/{activityUuid}/dates endpoint will include price information.
A list of useful selling points for the activity. Does not contain HTML. Does not include taxonomies. Translated based on the Accept-Language header value.
A list of inclusions. Does not contain HTML. Does not include taxonomies. Translated based on the Accept-Language header value.
The number of nights at a hotel that the activity includes.
Additional information about the activity, such as security or weather considerations. Contains HTML. Translated based on the Accept-Language header value.
Whether it is possible to reserve the activity for today or not.
Whether it is possible to reserve the activity for tomorrow or not.
The activity is able to accommodate people who speak any of the languages in this property. It is not necessarily required to select one of these languages during the reservation flow.
The activity has limited availability and is likely to completely sell out soon.
The activity is popular and has limited availability. Closer dates are likely to sell out quickly.
The maximum amount of time an activity provider needs to process a reservation request. Values follow the ISO 8601 standard.
This property is not used for instant confirmation activities.
Additional details about where customers will start the activity. Does not contain HTML. Translated based on the Accept-Language header value.
Additional details about where customers will start the activity in HTML. Translated based on the Accept-Language header value.
Additional details about where customers will start the activity in the Markdown markup language. Translated based on the Accept-Language header value.
The price for partners based on commercial agreements. Appears for authenticated requests.
An SEO-friendly description of the activity. Does not contain HTML. Translated based on the Accept-Language header value.
An SEO-friendly version of the activity title to use for search results. Does not contain HTML. Translated based on the Accept-Language header value.
When true, the activity provider must manually review and confirm (or refuse) each reservation. When this is the case, the activity is not instant confirmation.
A list of exclusions. Does not contain HTML. Does not include taxonomies. Translated based on the Accept-Language header value.
When true, affects the min_buy parameter in the /activities/{activityUuid}/dates/{date} endpoint for select seller gateways.
When true, the activity booking_type property has a value of NO-CALENDAR-FIXED-END or NO-CALENDAR-FIXED-VALIDITY.
A short summary of which days the activity is available. Contains HTML. Translated based on the Accept-Language header value.
Determines if pickups are a required part of the reservation flow. Value is an array with a single item, one of the following values:
tours-and-activities: Pickups are not part of the reservation flow.tours-and-activities-with-pickup: Customers must select a pickup point for a reservation.
The base price with a service fee, but no discount.
The base price with a discount, but no service fee.
This is the default property used to sort activities, typically from highest to lowest.
This property is used to sort activities by their venue, typically from highest to lowest.
The final price for customers.
The base price with a discount, but no service fee.
A breakdown of the number of reviews for the activity using a "five star" rating system, where a value of 0 is poor and a value of 5 is excellent.
The overall rating for this activity based on the reviews.
The total number of reviews for this activity.
An extra fee to add to the base price to cover additional costs for creating a reservation.
A list of customer-friendly services included in the activity.
An automatically generated URL-friendly slug based on the title property.
A combination of the slug property and the activity's numeric ID. This property is used for generating URLs for activities on musement.com.
The publication state of the activity and whether it is available for purchase
The typical publication flow follows:
DRAFT: The activity is being configured and is not available for purchase.REVIEW: The activity is being reviewed before publication and is not available for purchase yet.ONLINE: The activity has been published and is ready for purchase.
The status of an ONLINE activity can change when an activity is no longer available. It can change to either of the following statuses:
ARCHIVEDUNAVAILABLE
An activity that is not available may return to a status of ONLINE again.
Information about the activity provider.
The original currency the activity prices were loaded in, using a currency code from the /currencies endpoint.
When an activity includes a particular attraction, this property indicates if entry to the attraction is included in the final price or not.
The activity title, translated based on the Accept-Language header value.
Whether the content in the response is a translation for the Accept-Language header value or not.
The activity's UUID.
When the duration_range property is absent, this property indicates the maximum period of time the activity is valid for a customer once they start. Value follows the ISO 8601 standard.
When the property has a value of P0D, the activity does not have a well-defined length of time.
A list of venues the activity belongs to.
This property specifies if customers how customers need to present their vouchers to access a reserved activity:
- MOBILE: Vouchers on smartphones or tablets are accepted. Printed vouchers are also accepted.
- PRINTED: Vouchers must be printed. Vouchers on smartphones or tables are not accepted.
- MIXED: Voucher requirements vary depending on the selected product.
When an activity includes vouchers from activity providers, this property indicates whether customers must also receive a copy of the standard Musement voucher or not.
A street address for the location of the activity. Contains HTML. Translated based on the Accept-Language header value.
The duration of the activity, following the ISO 8601 standard.
Use the duration_range property instead.
General information on who can take advantage of reduced rates for the activity. Contains HTML. Translated based on the Accept-Language header value.
The number of customers who saved this activity to their favorites.
The integration which handles the reservation flow.
An automatically generated URL for the activity based on the activity properties and X-Musement-Market header value. The property value may consist of a single hashtag when no URL can be generated.
A list of verticals the activity belongs to. Since this property is deprecated, partners are expected to use categories instead.
Information related to delays or security concerns. Contains HTML. Translated based on the Accept-Language header value.
The type of entity the item represents.
A breakdown of the items within the list.
An SEO-friendly description of the list, translated based on the Accept-Language header value.
An SEO-friendly version of the list title to use for search results, translated based on the Accept-Language header value.
The list's subtitle, translated based on the Accept-Language header value.
This property is best used as the page header.
Temporary lists will eventually end and be removed from the /lists endpoint response.
The list's title, translated based on the Accept-Language header value.
This property is best used as a general title to give the page effect. For a page header, please use the subtitle property.
An automatically generated Musement URL for the list based on the X-Musement-Market header and list properties. The URL is only valid for select X-Musement-Market values and lists.
The number of customers who have saved this list to their favorites.
The list's verticals, if any.
A URL for the vertical's cover image.
An SEO-friendly description of the venue, translated based on the Accept-Language header value.
An SEO-friendly version of the venue name, translated based on the Accept-Language header value.
The vertical name, translated based on the Accept-Language header value.
The vertical slug, used for creating the vertical URL. Changes based on the value of the Accept-Language value.
An automatically generated Musement URL for the vertical based on the X-Musement-Market header and slug property. The URL is only valid for select X-Musement-Market values and active verticals.
{ "id": 244, "subtitle": "Top experiences in New York", "title": "Top experiences", "description": "Pressed for time? Or maybe you just want to know what you can't miss straight up. This list was made for you. It rounds up the best experiences of the city, from fabulous local dining to landmark attractions.", "seo_title": "Top experiences in New York", "seo_description": "Pressed for time? Or maybe you just want to know what you can't miss straight up. This list was made for you. It rounds up the best experiences of the city, from fabulous local dining to attractions.", "temporary": false, "url": "https://.sbox.musement.com/us/new-york/top-experiences-l/", "authors": [ { … } ], "list_type": { "id": 3, "name": "Musement list" }, "items": [ { … } ], "items_count": { "generic": 0, "thirdparty": 1, "musement": 9 }, "city": { "id": 55, "name": "New York", "cover_image_url": "https://images-sandbox.musement.com/cover/0002/42/view-on-manhattan-at-night-new-york-usa-jpg_header-141511.jpeg", "url": "https://.sbox.musement.com/us/new-york/", "time_zone": "America/New_York" }, "cover_image_url": "https://images-sandbox.musement.com/default/0001/59/thumb_58199_default_header.jpeg?w=750&h=500", "verticals": [ null ], "category": {} }