GET/v1/cost-breakdown

Get a detailed cost-of-living breakdown for a location vs a baseline

Return a detailed cost-of-living breakdown for a location, compared against a baseline country. Each category (food, housing, transport, health, etc.) is reported with its current CPI value, a percentage difference from the baseline, and a year-over-year trend arrow (`up` / `down` / `stable`). **When to use:** answer 'What does cost of living look like in Germany vs the US?', 'Which categories are cheaper in Japan compared to the UK?', or 'Build a per-category inflation dashboard'. **Inputs:** - `location` — country or city; accepts names, ISO codes, and major city aliases. - `compare_to` — baseline country (default `US`), same input formats. **Response shape:** a `CostBreakdown` with headline `overall_cpi` and `overall_vs_baseline_pct`, plus a `categories` list where each item has `category_code`, `category_name`, `value`, `vs_baseline_pct`, and `trend`. **Trend threshold:** yoy change > 0.5% = `up`, < -0.5% = `down`, otherwise `stable`. 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
location	query	string	required	Country or city — name or ISO code (e.g., 'Germany', 'Tokyo', 'US')
compare_to	query	string	optional	Baseline country for comparison (default: US)

Example request

curl

curl -X GET \
  "https://col.wageapi.com/api/v1/cost-breakdown?location=%3Clocation%3E&compare_to=US" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataCostBreakdownrequired

Full cost breakdown for a location with baseline comparison.

location_codestringrequired

ISO alpha-2 code of the queried location

location_namestringrequired

Name of the queried location

baseline_codestringrequired

ISO alpha-2 code of the baseline location

baseline_namestringrequired

Name of the baseline location

overall_cpianyoptional

Overall CPI value

one of:

option 1:

number

option 2:

null

overall_vs_baseline_pctanyoptional

Overall percentage vs. baseline

one of:

option 1:

number

option 2:

null

categoriesarray<CostBreakdownCategory>optional

Per-category breakdown with trends

array of CostBreakdownCategory

category_codestringrequired

category_namestringrequired

valueanyoptional

CPI index value for this category

one of:

option 1:

number

option 2:

null

vs_baseline_pctanyoptional

Percentage vs. baseline country (positive = more expensive)

one of:

option 1:

number

option 2:

null

trendstringoptionalenum: up | down | stable

Trend direction based on YoY change: 'up', 'down', or 'stable'

default "stable"

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

422`location` or `compare_to` could not be resolved to an ISO country code.

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 →