GET/v1/salary

Get salary benchmark data for a job title in any US metro or EU country

Return normalized salary benchmark data for a job title in any supported location. This is the primary salary lookup endpoint — it auto-detects whether the requested `location` is a US metro area or an EU country/city and returns the appropriate shape. **When to use:** answer questions like 'What do software developers earn in Berlin?', 'What is the median salary for nurses in Austin, TX?', or 'Look up the US national average for a data scientist'. **Location handling:** accepts BLS area codes, US metro names ('Austin, TX'), ISO country codes ('DE'), country names ('Germany'), or EU city names ('Berlin'). Location resolution may trigger a 400 `LOCATION_NOT_FOUND` if the input cannot be mapped — in that case retry with `GET /v1/salary/areas` or a broader name. **Response shape:** returns `SalaryResponse` (US — with percentiles p10-p90 and cost-of-living index) or `UnifiedSalaryResponse` (EU — with mean/median, gender pay gap, minimum wage). Both shapes carry `data_source` and `data_date` fields tagged with the originating dataset year. **Job title matching:** uses a 3-tier pipeline (alias → trigram → ILIKE). If no occupation matches, the endpoint returns 404 `NO_SALARY_DATA`. Use `GET /v1/jobs/search` beforehand when the caller is unsure of the title. 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 look up, e.g. 'Software Developer', 'Data Scientist', 'Nurse'
location	query	any	optional	US metro area (e.g. 'Austin, TX'), EU country (e.g. 'Germany', 'DE'), or EU city (e.g. 'Berlin'). Omit for US national average.
experience	query	any	optional	Planned feature — currently accepted but not applied to results
currency	query	string	optional	Currency code: 'USD' (default for US) or 'EUR' (default for EU)

Example request

curl

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

Responses

200Successful Response

one of:

option 1:

querySalaryQueryrequired

job_titlestringrequired

matched_socstringrequired

matched_titlestringrequired

locationstringrequired

experienceanyrequired

one of:

option 1:

string

option 2:

null

currencystringrequired

salarySalaryBandrequired

p10anyrequired

one of:

option 1:

number

option 2:

null

p25anyrequired

one of:

option 1:

number

option 2:

null

mediananyrequired

one of:

option 1:

number

option 2:

null

p75anyrequired

one of:

option 1:

number

option 2:

null

p90anyrequired

one of:

option 1:

number

option 2:

null

meananyrequired

one of:

option 1:

number

option 2:

null

sample_sizeanyrequired

one of:

option 1:

integer

option 2:

null

cost_of_living_indexanyoptional

one of:

option 1:

number

option 2:

null

data_sourcestringrequired

data_datestringrequired

related_titlesarray<string>optional

default []

array of string

string

option 2:

queryUnifiedSalaryQueryrequired

job_titlestringrequired

matched_titlestringrequired

locationstringrequired

regionstringrequiredenum: us | eu

matched_socanyoptional

one of:

option 1:

string

option 2:

null

matched_iscoanyoptional

one of:

option 1:

string

option 2:

null

matched_isco_fullanyoptional

one of:

option 1:

string

option 2:

null

match_methodanyoptional

one of:

option 1:

string

option 2:

null

country_codeanyoptional

one of:

option 1:

string

option 2:

null

experienceanyoptional

one of:

option 1:

string

option 2:

null

currencystringrequired

salaryUnifiedSalaryBandrequired

mediananyoptional

one of:

option 1:

number

option 2:

null

meananyoptional

one of:

option 1:

number

option 2:

null

p10anyoptional

one of:

option 1:

number

option 2:

null

p25anyoptional

one of:

option 1:

number

option 2:

null

p75anyoptional

one of:

option 1:

number

option 2:

null

p90anyoptional

one of:

option 1:

number

option 2:

null

sample_sizeanyoptional

one of:

option 1:

integer

option 2:

null

currencystringrequired

gender_gap_pctanyoptional

one of:

option 1:

number

option 2:

null

mean_maleanyoptional

one of:

option 1:

number

option 2:

null

mean_femaleanyoptional

one of:

option 1:

number

option 2:

null

cost_of_living_indexanyoptional

one of:

option 1:

number

option 2:

null

minimum_wageanyoptional

one of:

option 1:

monthly_euranyrequired

one of:

option 1:

number

option 2:

null

monthly_ppsanyrequired

one of:

option 1:

number

option 2:

null

yearintegerrequired

semesteranyoptional

one of:

option 1:

integer

option 2:

null

option 2:

null

data_sourcestringrequired

data_datestringrequired

notesarray<string>optional

default []

array of string

string

related_titlesarray<string>optional

default []

array of string

string

400Location could not be resolved to a US metro or EU country.

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

404No matching occupation or no published benchmark for this job/location pair.

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 →