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.
Example: city,state
limitnumber
Maximum number of results to return. Max 30. Default 10.
Example: 5

Response Schema

Returns an array of location objects. Note that unlike the Job object, these results only contain the ID for their specific kind.

Success Response Shape
[
  {
    "kind": "city",
    "name": "San Francisco",
    "display_label": "San Francisco, California, United States",
    "city_id": 5391959
  },
  {
    "kind": "state",
    "name": "California",
    "display_label": "California, United States",
    "state_id": 5332921
  }
]
kindstring
The specific type of the result: 'city', 'state', or 'country'.
namestring
The name of the geographic entity.
display_labelstring
A human-readable string for display in search results.
city_id | state_id | country_idnumber
The unique ID for the result. Only the ID matching the 'kind' is returned.
Usage Tip
Use the IDs from these results in the city_id, state_id, or country_id parameters of the GET /jobs endpoint for precise filtering.

Example Request

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