CleanJobData

Geo Suggest

Autocomplete and search for locations (cities, states, countries) to use as filters in the Jobs API. TypeScript types for response shapes live on the API types page.

GET
https://api.cleanjobdata.com/geo/suggest

Query Parameters

qstringRequired
The search query (e.g., city name, state, or country).
Example: San Fran
kindsstring
Comma-separated list of location types to include. Values: city, state, country. Omit to search across all three.
Example: city,state
limitnumber
Maximum number of results to return. Max 30. Default 10.
Example: 5

Response Schema

Returns an array of location objects. Every result has the same keys regardless of its kind — a state result simply has null city fields — and mirrors a row of a job's locations array, so a picked suggestion can be stored directly on a job posting.

Success Response Shape
[
  {
    "kind": "city",
    "name": "San Francisco",
    "display_label": "San Francisco, California, United States",
    "city_id": 5391959,
    "city_name": "San Francisco",
    "state_id": 5332921,
    "state_name": "California",
    "state_code": "CA",
    "country_id": 233,
    "country_name": "United States",
    "country_code": "US",
    "region": "Americas",
    "subregion": "Northern America",
    "lat": 37.77493,
    "lng": -122.41942,
    "timezone": "America/Los_Angeles"
  }
]
kindstring
The precision of the result: 'city', 'state', or 'country'. Use this — not which ID fields are non-null — to decide which /jobs filter to apply.
namestring
The name of the matched entity itself, whatever its kind.
display_labelstring
A human-readable string for display in search results, e.g. 'San Francisco, California, United States'.
city_id / city_namenumber | string | null
Populated on city results only; null for state and country results.
state_id / state_name / state_codenumber | string | null
The parent state, or the state itself on a state result. Null for country results.
country_id / country_name / country_codenumber | string | null
The parent country, or the country itself on a country result. Always populated. country_code is the ISO 3166-1 alpha-2 code.
region / subregionstring | null
The country's geographic region and subregion, e.g. 'Americas' and 'Northern America'.
lat / lngnumber | null
Coordinates of the matched entity itself, as numbers.
timezonestring | null
IANA timezone of the matched entity, falling back to its state's. Null for country results.
Usage Tip
Use the ID matching the result's kind in the city_id, state_id, or country_id parameter of the GET /jobs endpoint for precise filtering. The same result can also be stored as a job posting's location row — it carries the identical IDs our location normalizer resolves for ingested jobs, so a listing created this way is filterable by exactly the same queries.

Example Request

cURL
curl -X GET "https://api.cleanjobdata.com/geo/suggest?q=London&kinds=city" \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors & Rate Limits

A missing or invalid q returns a 400:

400 Response
{ "error": "Query parameter \"q\" is required and must be non-empty" }

This endpoint is rate limited like the rest of the API — see the Errors reference for the shared rate-limit and error envelope.