Locations

    Suggestions will appear below the field as you type

    Locations

      Suggestions will appear below the field as you type

      Locations

      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. While suburb-level locations are not yet available across all of our Asia-Pacific markets, the hierarchy is designed to be continuously revised and will be extended to address such gaps in the near future.
      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.

      Implementation options

      Locations can be implemented in one of two 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
        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.

        Operations

        The SEEK API provides three queries for looking up locations:
        1. locationSuggestions returns locations matching a provided text string.
        2. nearestLocations returns locations relevant to the provided geolocation, ordered by distance.
        3. location returns a location for a given SEEK location ID.

        locationSuggestions

        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). 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
        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
            }
          }
        }

        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
        query ($first: Int!, $geoLocation: GeoLocationInput!, $schemeId: String!) {
          nearestLocations(
            first: $first
            geoLocation: $geoLocation
            schemeId: $schemeId
          ) {
            id {
              value
            }
            name
            contextualName
            countryCode
          }
        }

        location

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