GET/v1/purchasing-power

Calculate PPP-adjusted equivalent salary between two countries

Calculate the equivalent salary needed in a target country to maintain the same standard of living as a source-country salary, using Purchasing Power Parity (PPP) conversion factors. Also returns a per-category breakdown showing which expense buckets are cheaper or more expensive in the target. **When to use:** answer 'What salary do I need in Germany to match $100K in the US?', 'How far does my EUR 60K salary go in Poland?', or 'Build a relocation bonus calculator'. **Inputs:** - `salary` — annual salary amount in the source currency. - `from` — source location (default `US`). - `to` — target location. - `currency` — ISO 4217 code for the salary (informational — no FX conversion is applied; the calculation is purely PPP-based). **Response shape:** a `PurchasingPowerResult` with `original_salary`, `equivalent_salary`, `adjustment_pct` (positive = target is more expensive), `adjustment_direction` (`higher` / `lower` / `equal`), `purchasing_power_ratio` (how much further money goes in target), and a `category_differences` list. Source: OECD PPP, World Bank ICP, BLS CPI, Eurostat HICP. Required scope: `costapi:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
salary	query	number	required	Annual salary amount
to	query	string	required	Target location — country name or ISO code
currency	query	string	optional	Currency ISO 4217 code
from	query	string	optional	Current location (default: US)

Example request

curl

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

Responses

200Successful Response

dataPurchasingPowerResultrequired

Result of a purchasing power calculation.

original_salarynumberrequired

Input salary amount

equivalent_salarynumberrequired

Salary needed in target location for same purchasing power

adjustment_pctnumberrequired

Percentage adjustment needed (positive = target is MORE expensive)

adjustment_directionstringrequiredenum: higher | lower | equal

Whether the target cost of living is higher, lower, or equal

purchasing_power_rationumberrequired

Ratio of purchasing power (>1 = money goes further in target)

currencystringoptional

Currency of the salary values

default "USD"

from_country_codestringrequired

from_country_namestringrequired

to_country_codestringrequired

to_country_namestringrequired

category_differencesarray<CategoryDifference>optional

Category-by-category price differences

array of CategoryDifference

category_codestringrequired

category_namestringrequired

from_valueanyoptional

one of:

option 1:

number

option 2:

null

to_valueanyoptional

one of:

option 1:

number

option 2:

null

difference_pctanyoptional

Percentage difference (positive = more expensive in target)

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

404PPP data missing for source or target country.

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

422Source or target location could not be resolved to an ISO 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 →