Skip to main content

​
Format Reference

The Geocode endpoint accepts a wide variety of location string formats. It handles messy, real-world input from job postings, user profiles, and ATS systems — including abbreviations, diacritics, transliterations, and ambiguous codes.
FormatExamples
City, State (US)San Francisco, CA · New York, NY · Austin, Texas · Portland, OR · Denver, Colorado · Raleigh, NC
City, CountryLondon, UK · Tokyo, Japan · Berlin, DE · Mumbai, India · Dubai, UAE · São Paulo, Brazil
City, Province (CA)Toronto, ON · Vancouver, BC · Montreal, QC · Calgary, AB · Ottawa, Ontario · Halifax, NS
City, State (AU)Sydney, NSW · Melbourne, VIC · Brisbane, QLD · Perth, WA
City, Constituent Country (UK)London, England · Edinburgh, Scotland · Cardiff, Wales · Belfast, Northern Ireland
City, Bundesland, GermanyMunich, Bavaria, Germany · Stuttgart, Baden-Württemberg
City, State, IndiaPune, Maharashtra, India · Bengaluru, Karnataka
Country codes (ISO alpha-2)US · GB · DE · FR · JP · IN · AU · CA · BR · SG
Country codes (ISO alpha-3)DEU · GBR · ITA · SWE · AUS · NZL · JPN · CHN
Country-first formatsGermany, Berlin · ITA, Rome · India, Mumbai
Full country namesUnited States · United Kingdom · Germany · Japan · South Korea
Country name variantsDeutschland · España · Schweiz · 日本 · भारत · Czechia · Türkiye
International / diacriticsMünchen, Deutschland · São Paulo, Brazil · Zürich, Switzerland · Köln, DE · Malmö, Sweden
City aliases & abbreviationsNYC · SF · LA · DC · CDMX · Bay Area · Silicon Valley · DFW · RTP
City transliterationsBombay (→ Mumbai) · Peking (→ Beijing) · Calcutta (→ Kolkata) · Madras (→ Chennai)
Well-known cities (standalone)London · Tokyo · Dubai · Singapore · Amsterdam · Dublin · Tel Aviv
Compound locationsUS or Canada · New York and San Francisco · London & Paris · EMEA or APAC
Remote keywordsRemote · Work from Home · Virtual · Distributed · Anywhere · WFH · Telecommute
Region aliasesEMEA · APAC · LATAM · DACH · BENELUX · NORDICS · ANZ · GCC · MENA
Ambiguous codesCA (California or Canada) · IN (Indiana or India) · DE (Delaware or Germany) · GA (Georgia state or country)

​
Compound Locations

The endpoint handles compound expressions with or, and, &, and / separators. Each part is resolved independently through the full pipeline, and results are merged into a single response with multiple locations. 
curl "https://connect.jobo.world/api/locations/geocode?location=US+or+Canada" \
  -H "X-Api-Key: YOUR_API_KEY"
Returns multiple locations: 
{
  "input": "US or Canada",
  "succeeded": true,
  "locations": [
    {
      "city": null,
      "region": null,
      "country": "United States",
      "latitude": 39.8283,
      "longitude": -98.5795,
      "display_name": "United States",
      "country_code": "US"
    },
    {
      "city": null,
      "region": null,
      "country": "Canada",
      "latitude": 56.1304,
      "longitude": -106.3468,
      "display_name": "Canada",
      "country_code": "CA"
    }
  ],
  "method": "pattern_parse"
}
How splitting works:
  1. The cleaned input is checked for compound separators: " or ", " and ", " & "
  2. If separators are found, the string is split into independent parts
  3. Each part is resolved separately through the pipeline (pattern parse → Photon → LLM)
  4. Results from all parts are merged into a single response
  5. The method field reflects the last method used across all parts
  6. The merged result is cached so subsequent requests are instant
Examples of compound splitting:
InputSplit Into
US or CanadaUS, Canada
New York and San FranciscoNew York, San Francisco
London & ParisLondon, Paris
EMEA or APACEMEA, APAC
Remote or San Francisco, CARemote, San Francisco, CA

​
Ambiguous Codes

Some 2-letter codes are ambiguous because they match both a US state abbreviation and an ISO country code. The pipeline uses a context-aware priority system to disambiguate: Ambiguous codes in the registry:
CodeUS StateCountry
CACaliforniaCanada
INIndianaIndia
DEDelawareGermany
GAGeorgia (state)Georgia (country)
COColoradoColombia
ALAlabamaAlbania
MEMaineMontenegro
NL(Newfoundland & Labrador)Netherlands
SKSaskatchewanSlovakia
Resolution rules:
  1. Standalone code → Prefers the US state interpretation. CA alone → California.
  2. Code paired with a city → Depends on context:
    • City looks like a known US city → US state. Los Angeles, CA → California.
    • City is a known foreign city → Country. Toronto, CA → Canada; Troisdorf, DE → Germany.
    • City is a known city for the colliding country → Country. Amsterdam, NL → Netherlands; Tel Aviv, IL → Israel.
  3. Three-letter code → Always treated as ISO alpha-3 country code. DEU → Germany.
  4. LLM fallback → For truly ambiguous cases where context clues are insufficient, the LLM tier uses world knowledge to make the best determination.
For best results with ambiguous codes, include a city name or use the full state/country name. For example, use "California" or "Canada" instead of "CA" when precision matters.

​
Tips for Best Results

Be specific

Include both city and state/country when possible. "San Francisco, CA" is better than just "CA".

Use full names for ambiguous codes

Use "California" or "Canada" instead of "CA". Use "Germany" instead of "DE".

Standard separators for compounds

Use "or", "and", or "&" between locations. "US or Canada" works; "US, Canada" may be treated as a single location.

Don't worry about case or diacritics

The pipeline normalizes case and handles diacritics. "münchen", "MÜNCHEN", and "Munchen" all resolve to Munich, Germany.

City aliases are supported

Common abbreviations like NYC, SF, LA, DC, and transliterations like Bombay, Peking are automatically resolved.

Noise is stripped automatically

Words like "remote", "hybrid", "onsite", "office", "headquarters", "metro", "greater" are stripped during cleaning. "Greater San Francisco Area" resolves to San Francisco, CA.

​
Error Handling

When geocoding fails, the response indicates the failure with succeeded: false and an error message. The method field will be no_match.

​
Common failure scenarios

Empty or whitespace input: 
{
  "input": "",
  "succeeded": false,
  "error": "Location string was empty."
}
Placeholder strings (e.g., from ATS systems): 
{
  "input": "2 Locations",
  "succeeded": false,
  "error": "Location string is a placeholder (e.g. '2 Locations'), not a real location."
}
Unresolvable location (all tiers failed): 
{
  "input": "xyzzy-unknown-place-12345",
  "succeeded": false,
  "method": "no_match",
  "error": "Could not geocode the provided location."
}
Even when geocoding fails for one location in a batch, other locations in the same request may succeed. Check the succeeded field on each individual result.