Nuances of Location Search
When using the location or location_advanced parameters you're effectively performing a search on the locations_derived field.
locations_derived is the normalized, geocoded version of each job's raw location data.
Locations are stored as full names (e.g. California, United States, Birmingham, England, United Kingdom), which is why your query needs to follow the same convention.
City/County, Region, Country
Each location in locations_derived follows the same structure: City/County, Region, Country
For the United States, the region is the state, whereas for the Netherlands the region is the province.
If our normalization was only able to recognize a County and no City, County will be set instead of city. locations_derived will not contain both City and County, but counties_derived will be set if a county is present in addition to a city.
County is searchable if present, even if city is present
Some countries have Municipalities instead of County. For those countries we set County (and respectively City) with the Municipality value. A county set with Municipality is not searchable at the moment
Nuances
-
For UK locations, the Region is the constituent country: England, Scotland, Northern Ireland, or Wales. For example:
London, England, United Kingdom -
The German cities Berlin and Hamburg don't have a region:
Berlin, Germany,Hamburg, Germany
English
The spelling of the locations in locations_derived is always in English. For example Munich and not Muenchen.
As a result, the location and location_advanced parameter require the English spelling as well.
Searching specific locations with the location parameter
When using the location parameter to search on a specific City or Region we recommend including the country and using double quotes as much as possible.
For example, if you search on Birmingham OR London, you might get results from Birmingham in the United States or London, Ontario, Canada.
Instead, search on:
"Birmingham, England, United Kingdom" OR "London, England, United Kingdom"
For more tips and tricks, please have a look at our Advanced Searching Guide
Geoapify
We use an API called Geoapify to normalize locations. If you're ever unsure what the correct location search parameters are you can use the Geoapify Playground. You can find the given City, State (Region), Country, County, and Municipality for a given query.
How location data is normalized to locations_derived
Our API is largely based on the Job Posting schema markup which is a universal standard of indexing and displaying jobs online. However, some ATS platforms are more diligent than others in ensuring all fields are kept up to date. For example, some ATS don’t include all location data in the schema, which is why we populate the locations_alt field with location data from the HTML. In addition, we’ve moved away from the Job Posting schema entirely for some ATS like Greenhouse, Taleo, and ADP.
Once a job is indexed we immediately normalize the raw location data with help from the Geoapify API.
First, we parse the 3 location fields separately: locations, locations_alt, and location_requirements.
Each field goes through a 14-step process where we try to discover the most accurate normalized location. The difficulty of getting an accurate match depends on the source. For example, a street address makes things easy, whereas a location field with just CA makes things difficult (is it Canada or California?).
Once we found a confident match we need to determine which of the 3 fields (now normalized) to use for locations_derived, which we do in the following order of priority:
locations_altwith at least one normalized location containing a citylocationswith at least one normalized location containing a citylocations_altwith at least one normalized location containing a regionlocationswith at least one normalized location containing a regionlocations_althas a location setlocationshas a location setlocation_requirements
The locations field
The locations field is structured like the 'jobLocation' standard from Google's JobPosting schema.
Even if the job source does not use JobPosting schema, we still parse the raw location data from the job page as such.
locations_alt
locations_alt is configured for select ATS for which the locations field is often inaccurate, not set, or contains hard-to-normalize data like office names.
For a number of ATS locations_alt is simply an alternative field present on the jobs page or ATS API.
For others, we use an LLM to help structure the data before saving to locations_alt. The LLMs receive a simple instruction to structure the data from one or more data points found on the jobs page in a format that works well with Geoapify.
location_requirements
location_requirements is structured like the 'applicantLocationRequirements' from Google's JobPosting schema.
We only capture this field if present in the exact JobPosting format.
location_requirements is the geographic location(s) in which employees may be located to be eligible for the work-from-home job.