Job categories

Job categories identify the occupational category of a position. Accurately categorising positions helps candidates search for the most relevant jobs. They are also used as an input into SEEK’s ad pricing.Job categories are represented as a two-level hierarchy from a general parent category to more specific child categories. For example, this is a small subset of the hierarchy for Information & Communication Technology:

Forward compatibility

SEEK periodically revises its job categories in response to changes in the employment market. While completely removing a job category would be considered a breaking change, other revisions can be made without notice:
  • New job categories can be added, both at the top level and as children of existing top-level job categories.
  • Existing job categories can be renamed to better reflect their intended purpose.
  • Deprecated job categories can be hidden from the jobCategorySuggestions and jobCategories queries.
We recommend dynamically querying job categories as part of your software’s job posting flow. This ensures hirers will be able to select from the latest SEEK job categories.

Before you begin

  • SEEK recommends using a browser token to query job categories 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 job categories from your backend using a partner token.

Implementation options

Job categories can be implemented in one of two ways. These are listed in order of preference.

Option 1: Support dynamic suggestions

You can dynamically retrieve and display job category suggestions in your job posting flow. This makes it easy for hirers to identify and select the most relevant job category for their position.
Loading suggested categories
Open in StorybookExample code on GitHub
Relevant job categories can be retrieved from the jobCategorySuggestions query. The details of the position should be supplied to the query to tailor suggestions.The Other fallback must be implemented to allow hirers to manually select a job category where the suggestions do not suffice. This is further documented as Option 2 below.

Option 2: Provide dropdown fields

If your software cannot dynamically retrieve suggestions or the suggestions lacked the desired option, you should allow hirers to manually select a job category from a set of dropdown fields.
Loading all categories
Open in StorybookExample code on GitHub
The top-level job categories and associated child categories can be retrieved from the jobCategories query.We recommend running this query when loading your job posting flow to ensure that you surface the latest job categories. You may use this method to cache job categories upfront, but the cache should be periodically refreshed to handle changes to the SEEK job category hierarchy. See forward compatibility for more details.

Operations

The SEEK API provides three queries for looking up job categories:
  1. jobCategorySuggestions will suggest job categories based on a partial PositionProfile.
  2. jobCategories will return the top-level categories for a scheme. You can use this as a starting point for selecting a specific child category.
  3. jobCategory returns the job category for a given ID.

jobCategorySuggestions

The jobCategorySuggestions query returns an array of suggested job categories based on a partial PositionProfile.While only the position’s title is required, providing more fields will increase the relevance of the suggestions. This can be used to interactively suggest job categories to a hirer while they’re posting a job ad.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $positionProfile: JobCategorySuggestionPositionProfileInput!
  $schemeId: String!
  $first: Int
) {
  jobCategorySuggestions(
    positionProfile: $positionProfile
    schemeId: $schemeId
    first: $first
  ) {
    jobCategory {
      id {
        value
      }
      name
      parent {
        id {
          value
        }
        name
      }
    }
    confidence
  }
}

jobCategories

The jobCategories query returns an array of top-level job categories based on a partial PositionProfile. These represent the most general job categories in the location’s hierarchy.You can use the top-level categories as a starting point for drilling down to a specific child category. For example, you might present the hirer with a dropdown of top-level categories that populates a second dropdown with its children.
QueryVariablesResult
CopyGraphQL Explorer
query (
  $schemeId: String!
  $positionProfile: JobCategories_PositionProfileInput!
) {
  jobCategories(schemeId: $schemeId, positionProfile: $positionProfile) {
    id {
      value
    }
    name
    children {
      id {
        value
      }
      name
    }
  }
}

jobCategory

The jobCategory query retrieves a job category by ID. This can be useful for debugging or exploratory testing:
QueryVariablesResult
CopyGraphQL Explorer
query ($id: String!) {
  jobCategory(id: $id) {
    id {
      value
    }
    parent {
      id {
        value
      }
      name
    }
    name
    children {
      id {
        value
      }
      name
    }
  }
}
Job posting features: Locations
Job posting features: Salary