Cities

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

To get a list of cities in the catalog, make the following request:

curl -X GET '{baseUrl}/cities' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

The endpoint is paginated so the results change based on the offset and limit query parameters. For more information, check out the pagination section.

Filtering by coordinates

You can filter results in the /cities endpoint around a specific set of coordinates. This query requires two parameters:

• coordinates : The latitude and longitude, separated by a comma.
• distance : The radius (in kilometers) around the coordinates to search.

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

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

Prioritizing a country

You can sort results in the /cities endpoint by indicating a country ID to prioritize. Cities belonging to that country are returned first, followed by any remaining cities (depending on other query parameters, if any).

In the example below, cities in Italy are prioritized and will appear first in the response:

curl -X GET '{baseUrl}/cities?prioritized_country=82' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

You can limit results for a prioritized country by using the prioritized_country_cities_limit parameter.

In the example request below, we are asking for four cities, prioritizing two results for Italy:

curl -X GET '{baseUrl}/cities?limit=4&prioritized_country=82&prioritized_country_cities_limit=2' \
-H 'X-Musement-Application: {applicationValue}' \
-H 'X-Musement-Version: 3.4.0' \
-H 'Authorization: Bearer {accessToken}'

Regardless of the value set for the prioritized_country_cities_limit parameter, the total number of results will never surpass the limit parameter (if set).