API reference

List regions

Return every country and ISO 3166-2 administrative region known to the index. Free of credit charges, authenticated and rate-limited, including with zero credits. Send an empty JSON object as the request body.

No credits consumed · Authentication and account rate limit apply.

POST /v1/regions

Request body

application/json · Up to 64 KiB. Unknown fields are rejected. Send your key in x-api-key.

No fields. Send an empty JSON object: {}.

Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

regions Region[]

Countries and administrative regions known to the index.
Nested fields
- adminCode string
  
  ISO 3166-2 administrative region code.
- adminLevel integer
  
  Administrative level.
  
  Range: 0–4294967295.
- countryCode string
  
  ISO 3166-1 alpha-2 country code.
- countryName string
  
  Country name.
- enName string
  
  English region name.
- localName string
  
  Local region name.
- parentAdminCode string
  
  Parent administrative region code, when available.

Errors

HTTP	Code	Meaning
400	invalid_argument	Invalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.
401	unauthenticated	The API key is missing, invalid, expired or revoked.
403	permission_denied	A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.
404	not_found	The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again.
429	resource_exhausted	The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry.
503	unavailable	The API is starting or the geocoder is temporarily unavailable.

Error handling and retries →