GET/v1/compare-cost-of-living

Compare cost of living between two countries or cities (agent-first)

Compare cost of living between two locations side by side. This is the primary semantic endpoint for 'how much more expensive is X vs Y?' questions — it accepts natural language inputs, resolves them to ISO country codes, and returns a headline CPI difference plus a per-category breakdown. **Accepted input formats for `from`/`to`:** country names in any major language ('Germany', 'Deutschland', 'Allemagne'), ISO 2-letter codes ('DE'), ISO 3-letter codes ('DEU'), ISO numeric codes ('276'), or major city names that map to a country. **Optional salary adjustment:** pass `salary` to also receive a PPP-based equivalent salary in the target location. The response `salary_adjustment` block is only populated when PPP data is available for both countries. **Response shape:** a `CostOfLivingComparison` with headline `overall_difference_pct` (positive = target is more expensive), a `categories` list with per-category CPI values and differences, and an optional `salary_adjustment`. Source: BLS CPI, Eurostat HICP, OECD CPI, OECD PPP, World Bank ICP. Required scope: `costapi:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
from	query	string	required	Source city or country — accepts names ('Germany'), ISO codes ('DE', 'DEU'), or numeric codes ('276').
to	query	string	required	Target city or country, same formats as 'from'.
salary	query	any	optional	Annual salary in source location currency. Calculates equivalent salary in target.
currency	query	string	optional	Currency ISO 4217 code

Example request

curl

curl -X GET \
  "https://col.wageapi.com/api/v1/compare-cost-of-living?from=%3Cfrom%3E&to=%3Cto%3E&salary=%3Csalary%3E&currency=USD" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

dataCostOfLivingComparisonrequired

Full cost-of-living comparison between two locations.

from_country_codestringrequired

ISO alpha-2 code of source location

from_country_namestringrequired

Name of source location

to_country_codestringrequired

ISO alpha-2 code of target location

to_country_namestringrequired

Name of target location

overall_difference_pctanyoptional

Overall CPI difference percentage (positive = target is more expensive)

one of:

option 1:

number

option 2:

null

categoriesarray<CategoryComparison>optional

Category-by-category comparison

array of CategoryComparison

category_codestringrequired

CPI category code (e.g., SA0, SAF, SAH)

category_namestringrequired

Human-readable category name

from_valueanyoptional

CPI value in the source location

one of:

option 1:

number

option 2:

null

to_valueanyoptional

CPI value in the target location

one of:

option 1:

number

option 2:

null

difference_pctanyoptional

Percentage difference (positive = target is more expensive)

one of:

option 1:

number

option 2:

null

salary_adjustmentanyoptional

Salary adjustment details (only if salary was provided)

one of:

option 1:

original_salarynumberrequired

Input salary in source location

equivalent_salarynumberrequired

Equivalent salary in target location

adjustment_pctnumberrequired

Percentage adjustment needed (positive = need more in target)

currencystringoptional

Currency of the salary values

default "USD"

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

422`from` or `to` location 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 →