# Search cities

Returns an array of cities.

Endpoint: GET /cities
Version: 3.5.0

## Header parameters:

  - `Accept-Language` (string)
    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)
    A partner's application value, used for analyzing API usage and to identify areas of improvement.

  - `X-Musement-Market` (string)
    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)
    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"

## Query parameters:

  - `coordinates` (string)
    Filter and sort results to cities closest to a provided latitude and longitude point.

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

  - `limit` (integer)
    Limit the maximum number of results to include in the response.

  - `offset` (integer)
    Exclude the first N results from the response, where N is the specified integer value.

  - `prioritized_country` (integer)
    Sort results so that cities which belong to the specified country appear first.

  - `prioritized_country_cities_limit` (integer)
    Limit the number of cities in the results which belong to the specified prioritized_country.

## Response 200 fields (application/json):

  - `activities_count` (integer)
    The number of available activities for the city.
    Example: 14

  - `id` (integer, required)
    The city's numeric ID.
    Example: 76

  - `code` (string, required)
    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"

  - `content` (string)
    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_html` (string)
    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>"

  - `country` (object, required)
    Example: {"id":184,"iso_code":"US","iso3char":"USA","name":"United States of America"}

  - `country.country_prefix` (string)
    The country's main telephone country code.
    Example: "+39"

  - `country.currency_code` (string)
    The main currency for the country as a Musement currency code. For a complete list of currencies, refer to the /currencies endpoint.
    Example: "EUR"

  - `country.iso_code` (string, required)
    The two-character ISO code for the country.
    Example: "US"

  - `country.iso3char` (string, required)
    The three-character ISO code for the country.
    Example: "USA"

  - `country.name` (string, required)
    The country's name, translated based on the Accept-Language header value.
    Example: "United States of America"

  - `country.id` (integer, required)
    The country's numeric ID. This property will be removed in the future.
    Example: 184

  - `cover_image_url` (string, required)
    A URL for the city's cover image.
    Example: "https://images-sandbox.musement.com/cover/0001/43/washington_header-42349.jpeg"

  - `event_count` (integer, required)
    The number of available activities for the city.

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

  - `latitude` (number, required)
    Example: 38.918

  - `longitude` (number, required)
    Example: -77.037

  - `list_count` (integer, required)
    The number of available Musement list pages for the city.

  - `meta_description` (string)
    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_title` (string)
    An SEO-friendly version of the city name, translated based on the Accept-Language header value.

  - `name` (string, required)
    The name of city, translated according to the Accept-Language header value.
    Example: "Washington DC"

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

  - `time_zone` (string, required)
    The city's time zone.
    Example: "America/New_York"

  - `top` (boolean, required)
    When true, the city is considered one of Musement's most popular cities.

  - `url` (string, required)
    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/"

  - `uuid` (string, required)
    The city's UUID.
    Example: "ec1dd48e-339d-11ea-ba3c-029a16533fe4"

  - `venue_count` (integer, required)
    The number of available venues in the city.
    Example: 1

  - `weight` (integer, required)
    A property used for ranking multiple cities by popularity. Top selling cities will have a higher value.
    Example: 2

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

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

## Response 404 fields (application/json):

  - `code` (string, required)
    The internal Musement code for the error.
    Example: "1400"

  - `message` (string, required)
    A message with a brief explanation of the error.
    Example: "No cities found matching search criteria"

## Response default fields (application/json):

  - `code` (string, required)
    The internal Musement code for the error.
    Example: "0"

  - `message` (string, required)
    A message with a brief explanation of the error.
    Example: "There was an error"