GET/v1/cheapest-cities

Rank the cheapest countries in a region by CPI

Return a ranked list of the cheapest countries in a given region, sorted by headline CPI (or a specific category like housing or food). Use this endpoint to power 'top-N cheapest places' lists for dashboards, relocation research, or budget-travel tools. **Region selector:** accepts curated region aliases — `world` (default), `EU`, `Europe`, `Asia`, `G7`, `G20`, `OECD`, `Nordic`, `Baltics`. The server resolves each alias to a fixed set of ISO country codes. **Category filter:** pass `category` to rank by a specific expense bucket instead of headline CPI. Accepts human-readable keywords ('housing', 'food', 'transport', 'health') or COICOP codes ('CP04'). **Top-N:** `top` (default 10, max 50) caps the result set size. **Response shape:** a list of `RankedLocation` items with `rank`, `country_code`, `country_name`, `cpi_value`, and `vs_average_pct` (difference from the group mean). Source: BLS CPI, Eurostat HICP, OECD CPI. Required scope: `costapi:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
region	query	string	optional	Region to search: 'EU', 'Europe', 'Asia', 'G7', 'OECD', 'Nordic', 'world'.
top	query	integer	optional	Number of results to return (1-50)
category	query	any	optional	Category keyword ('housing', 'food', 'transport') or COICOP code ('CP04').

Example request

curl

curl -X GET \
  "https://col.wageapi.com/api/v1/cheapest-cities?region=world&top=10&category=%3Ccategory%3E" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataarray<RankedLocation>required

array of RankedLocation

rankintegerrequired

Rank position (1 = cheapest)

country_codestringrequired

ISO alpha-2 country code

country_namestringrequired

Country name

cpi_valueanyoptional

Latest CPI index value

one of:

option 1:

number

option 2:

null

vs_average_pctanyoptional

Percentage vs. the group average (negative = cheaper than average)

one of:

option 1:

number

option 2:

null

metadataMetadataSchemarequired

sourcesarray<SourceSchema>optional

array of SourceSchema

namestringrequired

Data source name (e.g., 'BLS', 'OECD', 'Eurostat')

datasetstringrequired

Specific dataset identifier

urlanyoptional

URL to the source dataset

one of:

option 1:

string

option 2:

null

last_updatedanyoptional

When this data was last refreshed

one of:

option 1:

string (date-time)

option 2:

null

request_idstringrequired

Unique request identifier

rate_limitanyoptional

one of:

option 1:

remainingintegerrequired

Remaining requests today

daily_limitintegerrequired

Total daily request limit

reset_atstring (date-time)required

When the rate limit resets

option 2:

null

paginationanyoptional

one of:

option 1:

pageintegerrequired

page_sizeintegerrequired

totalintegerrequired

total_pagesintegerrequired

option 2:

null

data_vintageanyoptional

Data freshness (e.g., 'CPI data from February 2026')

one of:

option 1:

string

option 2:

null

methodology_notesanyoptional

Methodology notes (e.g., 'CPI rebased to 2020=100')

one of:

option 1:

string

option 2:

null

401Missing or invalid API key.

errorErrorDetailrequired

Structured error payload returned by all Aethar APIs. Mirrors the shape produced by aethar_auth.exception_handlers so the OpenAPI spec accurately describes real error bodies for documentation readers and MCP clients.

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

403API key lacks the required scope for this endpoint.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

422Unsupported region keyword.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

429Daily rate limit exceeded for this API key.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

500Unexpected server error. Includes a request_id for support.

errorErrorDetailrequired

codestringrequired

Machine-readable error code (e.g. INVALID_API_KEY)

messagestringrequired

Human-readable error message

statusintegerrequired

HTTP status code

request_idstringrequired

Request identifier — include in support tickets

suggestionanyoptional

Actionable hint on how to resolve the error

one of:

option 1:

string

option 2:

null

doc_urlanyoptional

Link to full documentation for this error code

one of:

option 1:

string

option 2:

null

fieldanyoptional

Field that caused the error (if applicable)

one of:

option 1:

string

option 2:

null

errorsanyoptional

Per-field validation errors (only for 422 VALIDATION_ERROR responses)

one of:

option 1:

array of object

object

option 2:

null

Try this endpoint

Create a free Aethar account and generate an API key in 2 minutes.

Create free account →