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, 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 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
        Open in Storybook
        View 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. This is less reliable than Option 2.
        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 such structure, you can provide the address as a single formatted line, though unstructured input may produce less consistent results:
        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
            }
          }
        }
        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
        AU
        suburb, postcode, country
        Cremorne, 3121, AU
        AU
        suburb, state, postcode, country
        Cremorne, VIC 3121, AU
        NZ
        suburb, region , country
        Milford Sound, Southland, NZ
        Other
        major city, province/state, country
        George Town, Penang, MY
        Other
        province/state, country
        Perak, MY
        The inferLocation query  will only return locations 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.
        If this occurs, the hirer will be unable to proceed to post their job ad to SEEK, and you should 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: Job categories
        Job Posting: Position openings
        Job Posting: Position openings