GET/v1/best-cities-for

Rank cities or countries by salary for an occupation

Return a ranked list of locations (US metros, EU countries, or both) sorted by mean salary for a given occupation. Use this when a caller needs a 'top-N best-paying places' list for a job title — relocation research, labour-market briefings, or dashboards. **When to use:** answer 'Where should I move as a software developer?', 'What are the best-paying EU countries for nurses?', or 'Rank top 20 US metros for data engineers'. **Region selector:** `US` (BLS OES metro areas), `EU` (Eurostat SES by country), or `all` (a merged set of both — note that direct mean comparison across currencies is approximate). **Response:** a list of `RankedCity` items with `rank`, `location`, `region`, `salary_mean`, `currency`, and `data_source`, plus a top-level `methodology_note` describing how the ranking was computed. **Note:** this endpoint ranks on salary only. For cost-of-living adjusted rankings, use `GET /v1/salary-adjusted` on the top candidates, or combine with CostAPI. Source: BLS OES (US), Eurostat SES (EU). Required scope: `salary:read`.

Authentication

Requires API key via X-API-Key header.

Parameters

Name	In	Type	Required	Description
occupation	query	string	required	Job title in natural language, e.g. 'Software Developer', 'Nurse'
region	query	string	optional	Region to search: 'US', 'EU', or 'all'
top	query	integer	optional	Number of results to return (1-50)

Example request

curl

curl -X GET \
  "https://salary.wageapi.com/api/v1/best-cities-for?occupation=%3Coccupation%3E&region=US&top=10" \
  -H "X-API-Key: YOUR_API_KEY"

Responses

200Successful Response

occupationstringrequired

matched_titlestringrequired

regionstringrequired

resultsarray<RankedCity>required

array of RankedCity

rankintegerrequired

locationstringrequired

regionstringrequiredenum: us | eu

salary_meannumberrequired

currencystringrequired

data_sourcestringrequired

methodology_notestringrequired

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

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 →