Top

Overview

The top tool ranks entities within a dimension by a selected metric. Use this tool when you need to identify leading employers, common skills, top schools, major occupations, or other highly ranked entities within a dataset.

Common Use Cases

Use top tool to answer questions such as:

Use Case	Example
Employer ranking	Which companies are posting the most jobs?
Skill ranking	Which skills are most common in a profile segment?
Education ranking	Which schools appear most frequently for a specific occupation or workforce segment?
Employer analysis	Identify companies leading hiring activity within a filtered market.
Skills analysis	Rank the skills most frequently requested in job postings or represented in profiles.
Education analysis	Identify schools or education programs represented in profiles.
Market exploration	Find the most common dimension values before refining filters.

Supported Datasets

The top tool supports the following datasets:

Dataset	Supported	Notes
Job Posting	Yes	Requires a `time` filter.
Profile	Yes	Supports ranking by profile-compatible dimensions.

Inputs

The tool accepts the following inputs.

Input	Description
`dataset`	The dataset to be analysed
`filter`	Filters are used to narrow the results. Ex `time`
`rankDimension`	Defines the dimension to rank. The object includes: `dimensionName` `level`
`rankBy`	A metric used to rank results.
`limit`	The maximum number of results to return. Minimum: `1` Maximum: `25` Default: `10`

Supported rank-by Metrics.

Dataset	Rank-by metrics
`job_postings`	`postings.unique_postings`, `postings.total_postings`, `postings.duplicate_postings`, `postings.posting_intensity`, `postings.unique_companies`
`profiles`	`profiles.unique_profiles`, `profiles.unique_schools`, `profiles.unique_companies`, `profiles.median_estimated_wage`

Select a ranking metric based on your analysis goals. For example, you can rank companies by posting volume, schools by profile count, or skills by workforce representation.

Example Request

{
  "dataset": "job_postings",
  "filter": {
    "time": {
      "level": 1,
      "values": {
        "start": "2024-01",
        "end": "2024-12",
        "postingType": "posted"
      }
    }
  },
  "rankDimension": {
    "dimensionName": "company",
    "level": 1
  },
  "rankBy": "postings.unique_postings",
  "limit": 5
}

Outputs

The response returns ranked results for the selected dimension.

Output	Description
`totals`	Aggregate metric totals for the request.
`rankings`	Ranked dimension values. Each ranking includes `id`, `name`, and metric fields.

The rankings can be used to identify the most prominent entities within a market and compare their relative importance based on the selected metric.

Example Response

{
  "totals": {
    "postings.unique_postings": 1250
  },
  "rankings": [
    {
      "id": "<company_id>",
      "name": "Example Employer",
      "postings.unique_postings": 95
    }
  ]
}