# 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](documentation/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](https://apidocs.geoapify.com/playground/geocoding/#autocomplete). 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_alt` with at least one normalized location containing a city
- `locations` with at least one normalized location containing a city
- `locations_alt` with at least one normalized location containing a region
- `locations` with at least one normalized location containing a region
- `locations_alt` has a location set
- `locations` has a location set
- `location_requirements`

## The `locations` field
The `locations` field is structured like the 'jobLocation' standard from [Google's JobPosting schema](https://developers.google.com/search/docs/appearance/structured-data/job-posting).
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.