Locations specify the geographical location of a position.
Precisely locating positions helps candidates search for the most relevant jobs.
They are also used as an input into SEEK’s ad pricing.
Locations are represented as a hierarchy from a larger parent location to smaller child locations.
The hierarchy starts with four top-level areas: Australia, New Zealand, UK and Other.
Depending on the location, the hierarchy becomes more specific until an individual suburb is identified.
For example, this is a subset of the location hierarchy for Victoria, Australia:
The existing SEEK location hierarchy was primarily designed to locate positions within Australia & New Zealand.
Its overseas locations don’t have sufficient granularity to support candidates searching for jobs in other markets.
To reflect its limited applicability, the existing hierarchy has been assigned the
seekAnz scheme.SEEK is designing a revised location hierarchy to better support overseas markets.
The revised hierarchy will be assigned a distinct scheme once it’s ready to integrate with.
This will allow your software to opt-in to the revised hierarchy by specifying its scheme ID.
- SEEK recommends using a browser token to query locations directly from a hirer’s browser. For the browser token to work, you will need to include the
query:ontologiesscope in your request. - You can also query locations from your backend using a partner token.
Locations can be implemented in one of two ways.
These are listed in order of preference.
You can include a SEEK-specific auto-suggest field in your job posting flow.
This affords the most control to your hirers, as they get to explicitly select the SEEK location for their job ad.
Suggestions will appear below the field as you type
Relevant SEEK locations can be retrieved from the
locationSuggestions query as the hirer types.
The hirer’s identifier should be supplied to the query to tailor suggestions to their SEEK-configured domicile.The
Detect button is an optional feature that allows the hirer to use their current location.
You can obtain a latitude and longitude from the geolocation API of their device or browser,
then pass that into the nearestLocations query.
The first returned result represents the closest SEEK location to the provided geolocation by distance.If your software already captures the position location based on an internal hierarchy,
you may wish to map this existing value to a SEEK location without additional input from the hirer.
This requires you to have the latitude and longitude associated with each location in your internal hierarchy.
In your job posting flow, prompt the user to select a location from your internal hierarchy as per usual.
Your software should then retrieve the associated geolocation and pass it into the
nearestLocations query as described in Option 1.We recommend running this query at time of job posting to ensure that you retrieve the latest SEEK location match.
You may use this method to build a mapping from your internal locations to their corresponding SEEK location IDs upfront,
but the mapping should be periodically refreshed to handle changes to the SEEK location hierarchy.
See forward compatibility for more details.
The SEEK API provides three queries for looking up locations:
locationSuggestionsreturns locations matching a provided text string.nearestLocationsreturns locations relevant to the provided geolocation, ordered by distance.locationreturns a location for a given SEEK location ID.
The
locationSuggestions query returns an array of likely locations for a provided text string.
You can limit the number of results using the first argument.This currently expects a substring of a location’s name (e.g. a suburb or city name).
Postcodes and street addresses are not supported.
You must use the
PositionPosting usage type when the suggestions will be used for posting a job ad.
This filters out locations that are too general to be associated with a job ad.QueryVariablesResult
Copy GraphQL Explorer
query (
$first: Int!
$hirerId: String!
$schemeId: String!
$text: String!
$usageTypeCode: String!
) {
locationSuggestions(
first: $first
hirerId: $hirerId
schemeId: $schemeId
text: $text
usageTypeCode: $usageTypeCode
) {
location {
id {
value
}
name
contextualName
countryCode
}
}
}The
nearestLocations query returns an array of locations closest to the specified latitude & longitude, ordered by distance.
You can limit the number of results using the first argument.This can be used to:
- Map from your own internal location hierarchy to a SEEK location.
QueryVariablesResult
Copy GraphQL Explorer
query ($first: Int!, $geoLocation: GeoLocationInput!, $schemeId: String!) {
nearestLocations(
first: $first
geoLocation: $geoLocation
schemeId: $schemeId
) {
id {
value
}
name
contextualName
countryCode
}
}The
location query returns the location for a given location ID.
This can be useful for debugging or exploratory testing:QueryVariablesResult
Copy GraphQL Explorer
query ($id: String!) {
location(id: $id) {
name
contextualName
countryCode
}
}