Skip to main content
Job postings describe places inconsistently: Store 04494 - Lynchburg, VA, münchen, US or Canada, 2 Locations. GET /api/locations/geocode resolves strings like these to canonical labels and coordinates. Search reads its location and locations filters with the same resolver, so a geocode call shows how a search will read a location.
Response
  • Each lookup costs $0.001 whether or not it resolves. Only a 4xx or 5xx is refunded. See Metered endpoints.
  • The same input normally resolves to the same result, so cache results on your side and look up each distinct string once.
  • Lookups count toward the Geocode rate-limit group. A sandbox key gets 404 with code: "not_available_in_sandbox".

​
How resolution works

Each input runs through up to four steps. The endpoint never calls a language model and never writes to the cache.
1

Clean and classify

Job-board decoration is stripped first: store-code prefixes (Store 04494 - ), trailing work-model notes such as (On-site), and wrapping parentheses. So Store 04494 - Lynchburg, VA resolves to Lynchburg. The cleaned input is then classified:Remote sentinels: Remote, Fully remote, Anywhere, Global, Worldwide, Work from home, WFH, Telecommute, Telework, Distributed, and forms such as Remote - EMEA, Remote / Travel, Hybrid/Remote or a trailing parenthetical.Placeholders:
  • Counts and quantifiers: 2 Locations, Multiple locations, Various cities, All offices
  • Single words: HQ, Headquarters, Office, Flexible, Hybrid, Onsite, N/A, TBD, TBA, Unknown
  • Scope words: Nationwide, Statewide, Corporate
  • Continents and sales regions: EMEA, APAC, LATAM, DACH, BENELUX, Nordics, ANZ, MENA, North America, Europe
2

Resolve codes and region names

An input that names a region or country outright resolves to it directly, ahead of the cache:
  • a bare US state code (TX) or country code (FR)
  • a region code with its own country (ON, Canada, TX, USA)
  • a US state, Canadian province or Australian state written in full (Ontario, New South Wales)
Ambiguous codes such as CA skip this step. See Ambiguous codes.
3

Cache lookup

The input is normalized into a cache key: abbreviations expanded, diacritics folded, case standardized. Inputs that differ only in case, accents or common abbreviations share an entry, so münchen, MÜNCHEN and Munchen all resolve to Munich, Germany.
  • A hit returns method: "cache".
  • A failure cached in the last 7 days returns succeeded: false with method: "cache_negative".
  • A cached result that contradicts a country or state the input names is ignored.
Jobo fills the cache while indexing jobs, so strings common in job postings are usually there.
4

Geocode each part

On a cache miss, the input is split into parts on or, and, &, ;, | and /. Names that contain a conjunction, such as Trinidad and Tobago or Newfoundland and Labrador, stay whole. The first five parts are geocoded, each on its own; further parts are ignored.
  • Placeholder parts are skipped, and remote parts become Remote entries.
  • Each geocoder candidate is scored by token overlap with the part. It must also lie in any country or state the part names, so Springfield, IL can’t resolve to Springfield, Massachusetts.
  • The best candidate is kept when its score clears a minimum. The score (0.0–1.0) comes back as fuzzy_confidence, and the labels are the geocoder’s canonical spelling.
If no part is kept, the response is no_match.

​
The method field

method names the branch that produced the result. Treat it as diagnostic and branch on succeeded, because new values can appear. fuzzy_confidence is null on cache hits and remote_keyword results.

​
Supported input formats

There is no fixed format grammar. These formats are common in job postings; the list is not exhaustive. An input the cache doesn’t hold resolves only if the geocoder can match it. Continents and sales regions are placeholders, not places (step 1). On their own, or as every part of a compound, they return succeeded: false.

​
Compound locations

Join locations with or, and, &, ;, | or /. Each part is geocoded on its own, and every resolved part comes back in one locations array. A comma isn’t a separator, so US, Canada may be read as one location.

​
Ambiguous codes

These two-letter codes are both a US state or Canadian province abbreviation and an ISO country code: How codes usually resolve:
Include a city, or spell the name out: California or Canada instead of CA, and Germany instead of DE.

​
Unresolvable input

An unresolvable location is not an error. The endpoint returns 200 with succeeded: false and still bills the lookup, so check succeeded, not the status code.
Of the succeeded: false results, retry only timeout and unavailable, and each retry is billed again. Retrying the others right away returns the same result. A missing or whitespace-only location parameter returns a real 400; see Errors for the envelope.

​
Location filters on the feed

POST /api/jobs/feed
The job feed and the managed feed don’t geocode. Their locations filter takes structured {country, region, city} entries:
  • country takes a country name or a case-insensitive code: US and USA match United States; GB, GBR and UK match United Kingdom. Leading and trailing spaces are ignored.
  • A code here always means a country, so CA is Canada and IN is India. In free text, a bare CA is ambiguous.
  • With a city, an entry filters by city and country; with only a region, by region and country; with neither, by country. Use full city and region names.
  • Multiple entries are OR’d.
  • An unknown country stays a literal filter. A misspelled country matches no jobs; it doesn’t lift the location restriction.
Every entry needs a country. An entry without one is ignored, and if no entry has a country, the feed isn’t filtered by location at all.

Geocode a location

Parameters, response schema and status codes for GET /api/locations/geocode.

Job locations

The location fields every job carries.