Job Location Normalization

Location is one of the most important filters in a job board. JobsDataAPI normalizes messy location data into structured fields so your application can filter by city, state, country, or remote status without string matching.

Location Fields

Every job can include:

• location — the original display string
• locations — an array of normalized location rows
• has_remote — whether the job is remote

A normalized location row can include:

{
  "kind": "city_state_country",
  "is_primary": true,
  "city_id": 123,
  "city_name": "San Francisco",
  "state_id": 456,
  "state_code": "CA",
  "country_id": 233,
  "country_code": "US",
  "lat": 37.7749,
  "lng": -122.4194,
  "timezone": "America/Los_Angeles"
}

Filtering by Location

Use structured IDs when possible:

curl "$CLEANJOBDATA_API_BASE_URL/jobs?city_id=123&remote=true" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

You can also filter by state or country:

curl "$CLEANJOBDATA_API_BASE_URL/jobs?state_id=456&title=engineer" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

curl "$CLEANJOBDATA_API_BASE_URL/jobs?country_id=233&experience_level=SE" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

For country-code fallback, use location:

curl "$CLEANJOBDATA_API_BASE_URL/jobs?location=US&title=engineer" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Getting Location IDs

Use the geo suggest endpoint to resolve user input into IDs:

curl "$CLEANJOBDATA_API_BASE_URL/geo/suggest?q=San%20Francisco&kinds=city,state,country&limit=10" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

The response contains rows with one of:

• city_id
• state_id
• country_id

Use the returned ID in your jobs query.

Remote Jobs

Remote jobs are handled with has_remote and remote=true:

curl "$CLEANJOBDATA_API_BASE_URL/jobs?remote=true&title=engineer" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

You can combine remote with location filters when you want remote jobs in a specific market:

curl "$CLEANJOBDATA_API_BASE_URL/jobs?remote=true&location=US&title=engineer" \
  -H "Authorization: Bearer $CLEANJOBDATA_API_KEY"

Why This Matters

Normalized locations make it possible to build:

• city pages
• state pages
• country pages
• remote-only feeds
• location chips
• map views
• regional analytics
• SEO landing pages

Without normalization, every filter becomes a fragile string comparison.

Recommended Implementation

1. Use /geo/suggest for user-entered locations.
2. Store the returned city_id, state_id, or country_id.
3. Query /jobs with the matching location filter.
4. Use has_remote and remote=true for remote filtering.
5. Avoid matching raw location strings unless you only need display text.

Location normalization gives your job board the structure it needs to filter reliably and build better search experiences.