List all 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
}

GET

api

public

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.

image.url is a protocol-relative URL (e.g. //cdn-imgix.headout.com/...) — prepend a scheme (https:) before rendering it.

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.

Show child attributes

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.

Before you get started

List all collections

⌘I

Guide

Cities

Collections

Categories

Subcategories

Products

Availabilities

Bookings

Authorizations

Query Parameters

Response