Type-ahead over every place in the jobs corpus — countries, states, cities and regions — in one ranked list. Built to be called per keystroke and to hand back a value you can feed straight into a jobs query.
Using a result. Every row carries a kind and a code; kind tells you which filter the code belongs to:
kind | example code | jobs filter |
|---|---|---|
country | US | country |
state | US-TX | state |
city | austin-tx-us | the location filter |
region | emea | the location filter |
Codes are opaque identifiers — switch on kind and pass code through verbatim rather than parsing it. (City and region codes are accepted by the location filter; until that filter ships, country and state suggestions are the ones you can act on.)
Matching. q is matched case- and diacritic-insensitively (zurich finds Zürich, sao paulo finds São Paulo) as a substring of the place name. A two-character q additionally matches country and state codes exactly, so ny finds New York and de finds Germany — abbreviations are how people type states, and no name-based match can serve them. That code tier disappears at the third keystroke.
Ranking. Exact two-letter code matches first, then names that START with q, then names that merely contain it. Within a tier, larger places come first (population, descending), with country > state > city > region as the tiebreak between equally sized places. Consequences worth knowing: a bare q is global, so dal ranks Dalian above Dallas — scope with country for a regional board; and at exactly two characters, code matches outrank even large cities (la → Laos, Louisiana, then Lahore).
Regions are the five multi-country buckets, matched by name like anything else: amer (Americas), apac (Asia-Pacific), emea (Europe, Middle East & Africa), latam (Latin America), worldwide. They belong to no single country, so supplying country excludes them.
Suggestions are drawn from the location dimension, which only contains places that have been seen on a job posting. It does not tell you how many jobs are OPEN there today — a suggestion can resolve to zero current results.
Authorization
bearerAuth Provide your secret API key (prefixed sk_) as a bearer token: Authorization: Bearer sk_....
In: header
Query Parameters
The typeahead query. Matched case- and diacritic-insensitively against location names (prefix matches rank above substring matches), plus an exact two-letter country/state code match (q=ny finds New York). 1-100 characters after trimming.
1 <= length <= 100Restrict suggestions to these ISO 3166-1 alpha-2 country codes. Repeat the parameter or comma-separate values (e.g. country=us,ca). Up to 20 values; case-insensitive. Region rows (emea, apac, …) belong to no country and are therefore never returned when this filter is supplied.
items <= 20Maximum number of suggestions to return. Defaults to 10; values above 25 are clamped to 25.
0 < value10Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/locations/search?q=string"{ "data": [ { "kind": "country", "code": "string", "name": "string", "admin1_code": "string", "admin1_name": "string", "country_code": "string", "country_name": "string", "population": 0 } ]}{ "type": "string", "title": "string", "status": 0, "detail": "string", "errors": [ { "field": "string", "message": "string" } ]}{ "type": "string", "title": "string", "status": 0, "detail": "string", "errors": [ { "field": "string", "message": "string" } ]}{ "type": "string", "title": "string", "status": 0, "detail": "string", "errors": [ { "field": "string", "message": "string" } ]}