List locations

Returns bounded location typeahead results. Empty catalogue requests are rejected; use a canonical location ID for exact retrieval.

GET/v0/locations

Authentication

bearerAuth · http bearer

Organisation API key supplied only through the Authorization header.

Required scopes: catalogues:read.

Parameters

Name	Type	Description
`query`required	stringquery	Case-insensitive typeahead text. At least 2 characters are required; empty catalogue dumps are not supported. Schema and examples `string` Case-insensitive typeahead text. At least 2 characters are required; empty catalogue dumps are not supported. Examples `["london"]` Maximum length `100` Minimum length `2` example-1: `london`
`cursor`optional	stringquery	Opaque pagination cursor. Schema and examples `string` Opaque pagination cursor. Maximum length `1000` Minimum length `1`
`limit`optional	integerquery	Maximum resources to return, from 1 to 20. Defaults to 20. Schema and examples `integer` Maximum resources to return, from 1 to 20. Defaults to 20. Default `20` Maximum `20` Minimum `1`
`type`optional	stringquery	Restrict results to one canonical location resource kind. Schema and examples `string` Restrict results to one canonical location resource kind. Allowed values `["region","country","admin","metro","city"]` Examples `["metro"]` example-1: `metro`
`parent`optional	stringquery	Restrict results to locations contained by this canonical parent ID, such as country:GB or metro:oecd:GB:london. Schema and examples `string` Restrict results to locations contained by this canonical parent ID, such as country:GB or metro:oecd:GB:london. Examples `["country:GB"]` Maximum length `240` Minimum length `1` example-1: `country:GB`

Responses

The requested catalogue resource.

application/json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

LocationListLocationList

Additional properties: forbidden

Properties

datarequired

object[]

Maximum items: 20

Items

object

Additional properties: forbidden

Properties

countryrequired

string | null

anyOf

Option 1

string

Pattern: ^[A-Z]{2}$

Option 2

null

idrequired

string

Maximum length: 240
Minimum length: 1

kindrequired

string

Allowed values: ["region","country","admin","metro","city"]

labelrequired

string

Maximum length: 240
Minimum length: 1

objectrequired

string

Constant: location

parent_idsrequired

string[]

Maximum items: 20

Items

string

Maximum length: 240
Minimum length: 1

has_morerequired

boolean

next_cursorrequired

string | null

anyOf

Option 1

string

Maximum length: 1000

Option 2

null

objectrequired

string

Constant: list

The request contains an invalid parameter, parameter combination, or cursor.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The organisation API key is missing, invalid, expired, or revoked.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The organisation does not have enough credit to reserve this operation.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The authenticated organisation lacks the required scope, or the browser origin is not allowed.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The requested resource does not exist or is not available to this organisation.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The server did not complete the request in time. This failure is non-billable and may be retried.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

Retry-Afteroptional

Minimum number of seconds before retrying when supplied.

integer

Minimum: 0

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The organisation request rate was exceeded. Retry after the indicated delay.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

Retry-Afteroptional

Minimum number of seconds before retrying when supplied.

integer

Minimum: 0

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

The service or durable usage settlement is temporarily unavailable. This failure is non-billable.

This response uses Problem Details.

application/problem+json

Cache-Controlrequired

Public cache policy for the bounded catalogue response.

string

ETagrequired

Strong representation validator for conditional GET requests.

string

Retry-Afteroptional

Minimum number of seconds before retrying when supplied.

integer

Minimum: 0

traceparentrequired

W3C trace context generated for this request attempt.

string

Pattern: ^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$

X-Request-Idrequired

Unique UUIDv7 identifier for this request attempt.

string<uuid>

Format: uuid

ProblemDetailsProblemDetails

Additional properties: forbidden

Properties

available_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

coderequired

string

Maximum length: 80
Minimum length: 1

detailrequired

string

Maximum length: 1000
Minimum length: 1

errorsoptional

object[]

Maximum items: 100

Items

object

Additional properties: forbidden

Properties

coderequired

string

Maximum length: 80
Minimum length: 1

messagerequired

string

Maximum length: 500
Minimum length: 1

pointerrequired

string

Pattern: ^\/.*

instancerequired

string

Pattern: ^\/.*

paramoptional

string

Maximum length: 160
Minimum length: 1

request_idrequired

string<uuid>

Format: uuid
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$

required_credit_usdoptional

string

Pattern: ^(?:0|[1-9]\d*)\.\d{2,6}$

retryablerequired

boolean

statusrequired

integer

Maximum: 599
Minimum: 400

titlerequired

string

Maximum length: 120
Minimum length: 1

top_up_urloptional

string<uri>

Format: uri
Maximum length: 2048

typerequired

string<uri>

Format: uri
Maximum length: 2048

Pagination

Property	Value
Allows page size change	`true`
Cursor ttl seconds	`86400`
Has more path	`has_more`
Items path	`data`
Next cursor path	`next_cursor`
Style	`keyset`