GET/v1/salary/compare

Compare salaries across up to 10 US metros and EU countries

Compare salary benchmarks for the same job title across up to 10 locations in a single request. Locations can mix US metro areas, EU countries, and EU cities — the server resolves each one independently and merges the results. **When to use:** answer questions like 'How do developer salaries compare between Austin TX, Berlin, and Paris?' or 'Build me a relocation comparison table for a data scientist across 5 cities'. **Format:** `locations` is a semicolon-separated list, max 10 entries. Example: `Austin, TX;Berlin;Germany`. The server trims whitespace and preserves order. Any one unresolved location raises 400 `LOCATION_NOT_FOUND` for the whole request, so pre-validate with `GET /v1/salary` if the caller is unsure. **Response:** `UnifiedCompareResponse` with a per-location item including median/mean, currency, cost-of-living adjusted median (US only), gender pay gap and minimum wage (EU only), and the source dataset tag. Source: BLS OES (US) or Eurostat SES (EU). Required scope: `salary:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
job_title	query	string	required	Job title to compare, e.g. 'Software Developer'
locations	query	string	required	Semicolon-separated locations (US metros, EU countries, or EU cities). e.g. 'Austin, TX;Berlin;Germany'. Max 10.
experience	query	any	optional	Planned feature — currently accepted but not applied to results
currency	query	string	optional	Currency code: 'USD' or 'EUR'

Example request

curl

curl -X GET \
  "https://salary.wageapi.com/api/v1/salary/compare?job_title=%3Cjob_title%3E&locations=%3Clocations%3E&experience=%3Cexperience%3E&currency=USD" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

job_titlestringrequired

comparisonsarray<UnifiedComparisonItem>required

array of UnifiedComparisonItem

locationstringrequired

regionstringrequiredenum: us | eu

country_codeanyoptional

one of:

option 1:

string

option 2:

null

mediananyoptional

one of:

option 1:

number

option 2:

null

meananyoptional

one of:

option 1:

number

option 2:

null

currencystringrequired

col_indexanyoptional

one of:

option 1:

number

option 2:

null

col_adjusted_mediananyoptional

one of:

option 1:

number

option 2:

null

gender_gap_pctanyoptional

one of:

option 1:

number

option 2:

null

minimum_wage_monthly_euranyoptional

one of:

option 1:

number

option 2:

null

data_sourcestringrequired

notesarray<string>optional

default []

array of string

string

400Too many locations or an unresolved location in the list.

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

401Missing or invalid 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

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

422Request validation failed (bad JSON shape, missing required fields, etc.).

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 →