Skip to main content
GET
/
api
/
public
/
v2
/
cities
curl --location 'https://www.headout.com/api/public/v2/cities/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

{
  "cities": [
    {
      "code": "AMSTERDAM",
      "name": "Amsterdam",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/ee075882083344be170ed38c8c76b4a1-amsterdam.jpeg"
      },
      "country": {
        "code": "NL",
        "name": "Netherlands"
      },
      "timezone": "Europe/Amsterdam"
    },
    {
      "code": "BARCELONA",
      "name": "Barcelona",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/4b075882083344be170ed38c8c76b4a1-barcelona.jpeg"
      },
      "country": {
        "code": "ES",
        "name": "Spain"
      },
      "timezone": "Europe/Madrid"
    },
    {
      "code": "BERLIN",
      "name": "Berlin",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/2a075882083344be170ed38c8c76b4a1-berlin.jpeg"
      },
      "country": {
        "code": "DE",
        "name": "Germany"
      },
      "timezone": "Europe/Berlin"
    }
  ],
  "nextUrl": "/api/public/v2/cities/?offset=20&limit=20",
  "prevUrl": null,
  "total": 142,
  "nextOffset": 20
}
Returns a paginated list of discoverable cities on Headout. Each city includes a code (used as cityCode in other endpoints), a display name, an image, the country it belongs to, and its IANA timezone. Results are sorted alphabetically by city name. Use the cityCode to filter the Products endpoint. 
curl --location 'https://www.headout.com/api/public/v2/cities/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

{
  "cities": [
    {
      "code": "AMSTERDAM",
      "name": "Amsterdam",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/ee075882083344be170ed38c8c76b4a1-amsterdam.jpeg"
      },
      "country": {
        "code": "NL",
        "name": "Netherlands"
      },
      "timezone": "Europe/Amsterdam"
    },
    {
      "code": "BARCELONA",
      "name": "Barcelona",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/4b075882083344be170ed38c8c76b4a1-barcelona.jpeg"
      },
      "country": {
        "code": "ES",
        "name": "Spain"
      },
      "timezone": "Europe/Madrid"
    },
    {
      "code": "BERLIN",
      "name": "Berlin",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/2a075882083344be170ed38c8c76b4a1-berlin.jpeg"
      },
      "country": {
        "code": "DE",
        "name": "Germany"
      },
      "timezone": "Europe/Berlin"
    }
  ],
  "nextUrl": "/api/public/v2/cities/?offset=20&limit=20",
  "prevUrl": null,
  "total": 142,
  "nextOffset": 20
}

Authorizations

​
Headout-Auth
string
header
required

Query Parameters

​
offset
integer
default:0

Number of cities to skip. Defaults to 0. Increment by the limit value (default 20) to fetch subsequent pages.

​
limit
integer
default:20

Maximum number of cities per page. Defaults to 20. Values above 20 are capped to 20.

Required range: x <= 20

Response

Successful response

​
cities
object[]

The cities in this page of results.

​
nextUrl
string | null

Relative URL to fetch the next page of results. Null if on the last page.

​
prevUrl
string | null

Relative URL to fetch the previous page of results. Null if on the first page.

​
total
integer

Total number of discoverable cities across all pages.

​
nextOffset
integer | null

Offset value for the next page. Null if on the last page.