Locations

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 supports increased granularity in core Asia-Pacific locations where the SEEK Group operates. It starts with top-level areas and becomes more specific until an individual suburb is identified, and is designed to be continuously revised to address gaps and realignments over time.
Code
Name
AU
Australia
HK
Hong Kong
ID
Indonesia
MY
Malaysia
NZ
New Zealand
PH
The Philippines
SG
Singapore
TH
Thailand
The hierarchy only extends to the country level (e.g. Fiji) outside of these core Asia-Pacific locations.For example, this is a subset of the location hierarchy for Victoria, Australia:

Remote work

If a hirer is recruiting for a remote position that is not tied to a specific geographical location, they can include work from home or WFH in their position title or advertisement details. SEEK will recognise these keywords and surface the position as appropriate across our employment marketplace, including under the “Work from home” search option.A location is still required for a remote position; this can be set to the headquarters or local branch of the hirer’s organization.

Before you begin

  • 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:ontologies scope in your request.
  • You can also query locations from your backend using a partner token.

Contextual names

SEEK’s location queries return a common Location object that has both a name and a contextualName. When displaying a list of locations to a hirer, you should use the contextualName as it provides more precise information. For example, when displaying the results of the locationSuggestions query to a user, some results may be ambiguous if only the name value is displayed.
name
contextualName
Richmond
Richmond NSW 2753 AU
Richmond
Richmond VIC 3121 AU
Richmond
Richmond Otago NZ

Implementation options

Locations can be implemented in one of three ways. These are listed in order of preference.

Option 1: Build a SEEK-specific location input

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
    Open in StorybookExample code on GitHub
    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.

    Option 2: Map from your internal location hierarchy

    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.

    Option 3: Use location inference

    If you don’t have the latitude and longitude associated with each location in your internal hierarchy, you may use other structured information to infer a SEEK location without additional input from the hirer.In your job posting flow, prompt the user to select a location from your internal hierarchy as per usual. Your software should then retrieve structured address details of the location and pass it into the inferLocation query.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 and improvements to our inference capability.

    Operations

    The SEEK API provides three queries for looking up locations:
    1. locationSuggestions returns locations matching partial text input for an interactive autocomplete user experience.
    2. nearestLocations returns locations relevant to the provided geolocation, ordered by distance.
    3. inferLocation returns a location matching structured address details for programmatic mapping.
    4. location returns a location for a given SEEK location ID.

    locationSuggestions

    The locationSuggestions query returns an array of likely locations for partial text input. 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). Street addresses are not supported, and postcodes are only supported in Australia at this time.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
    CopyGraphQL 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
          }
          contextualName
          countryCode
    

          # Enable your software to pre-select a salary currency
          currencies {
            code
          }
        }
      }
    }

    nearestLocations

    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:
    • Suggest the location nearest to an end user based on their geolocation from a built-in platform  or web  API.
    • Map from your own internal location hierarchy to a SEEK location.
    QueryVariablesResult
    CopyGraphQL Explorer
    query ($first: Int!, $geoLocation: GeoLocationInput!, $schemeId: String!) {
      nearestLocations(
        first: $first
        geoLocation: $geoLocation
        schemeId: $schemeId
      ) {
        id {
          value
        }
        contextualName
        countryCode
    

        # Enable your software to pre-select a salary currency
        currencies {
          code
        }
      }
    }

    inferLocation

    The inferLocation query returns a location matching structured address details for programmatic mapping. This query will attempt to match the details to a location in our hierarchy on a best-effort basis.
    QueryVariablesResult
    CopyGraphQL Explorer
    query ($address: SeekPositionAddressInput!, $schemeId: String!) {
      inferLocation(address: $address, schemeId: $schemeId) {
        id {
          value
        }
    

        # Enable your software to pre-select a salary currency
        currencies {
          code
        }
      }
    }
    If your location hierarchy lacks separate postalCode data, you can provide the address as a single formatted line along with a country code, though this may produce less consistent results for some locations:
    QueryVariablesResult
    CopyGraphQL Explorer
    query ($address: SeekPositionAddressInput!, $schemeId: String!) {
      inferLocation(address: $address, schemeId: $schemeId) {
        id {
          value
        }
    

        # Enable your software to pre-select a salary currency
        currencies {
          code
        }
      }
    }

    inferLocation input formats

    SEEK will infer a location based on the closest match to the supplied text. You should test and fine tune the data format provided by your software, starting with the following recommended baselines:
    Country
    Fields
    Example formattedAddress
    Example countryCode
    Example postCode
    Response contextualName
    Australia
    suburb
    Cremorne
    AU
    3121
    Cremorne VIC 3121 AU
    Australia
    suburb, state
    Richmond, VIC
    AU
    3121
    Richmond VIC 3121 AU
    New Zealand
    suburb, region 
    Richmond, Tasman
    NZ
    Richmond, Tasman NZ
    Philippines
    city
    Makati
    PH
    Makati City Metro Manila PH
    Singapore
    city
    Tiong Bahru
    SG
    150167
    Tiong Bahru Central Region SG
    Malaysia
    city, province/state
    George Town, Penang
    MY
    George Town Penang MY
    Indonesia
    city, province/state
    Kembangan, Jakarta
    ID
    Kembangan Jakarta ID
    Hong Kong
    city, province/state
    Tai Koo, Eastern District
    HK
    Tai Koo Eastern District HK
    The inferLocation query will only return a single location suitable for posting a job ad, similar to the PositionPosting usage type for locationSuggestions, and will return null if a valid location cannot be inferred from the provided data.Issues typically occur when the location data supplied is too broad or ambiguous, such as the examples below:
    formattedAddress
    countryCode
    postCode
    Response
    Malaysia
    MY
    nullLocation is too broad
    New South Wales
    AU
    nullLocation is too broad
    Richmond
    AU
    Richmond QLD 4822 AUPotential for mismatch, for example if user intended Richmond VIC. Including postcode will aid accuracy of results.
    If null is returned, the hirer will be unable to proceed to post their job ad to SEEK and you should:
    1. Surface meaningful and actionable error messaging to users within the job posting flow, providing an opportunity to amend the location before retrying. For example: Unable to retrieve location for SEEK. Update your location and ensure you are entering a granular city or suburb.
    2. Review the quality of the address details that your software sends to the SEEK API

    location

    The location query returns the location for a given location ID. This can be useful for debugging or exploratory testing:
    QueryVariablesResult
    CopyGraphQL Explorer
    query ($id: String!) {
      location(id: $id) {
        name
        contextualName
        countryCode
    

        # Enable your software to pre-select a salary currency
        currencies {
          code
        }
      }
    }
    Job posting features: Identifiers & references
    Job posting features: Job categories