Performing a complex boolean query

POST/api/v1.1/{country_code}/query-builder/run-query/

Supports running complex boolean queries on our dataset.

Queries can be based around a demand or salary primary metric, contain one or more filter rules, and an optional breakdown.

Request

Authorization: API Key

Add parameter in header

Authorization

Example

Authorization: 2f68dbbf-519d-4f01-9636-e2421b68f379

Path Params

country_code

string

required

A two character code that specifies which country dataset to query.

Example:

Match pattern:

^[a-z]{2}$

metric

enum<string>

required

The metric to be reported.

Allowed values:

demandsalary

date_range

required

The date range to be used for the report.

One of

AbsoluteDateRange

RelativeDateRange

type

enum<string>

required

Specifies the date range as absolute.

Allowed value:

absolute

start

string <date>

required

The start date for the date range in ISO8601 format (YYYY-MM-DD).

Example:

2023-07-19

Match pattern:

^([0-9]{4})(-?)(1[0-2]|0[1-9])\2(3[01]|0[1-9]|[12][0-9])$

end

string <date>

required

The end date for the date range in ISO8601 format (YYYY-MM-DD).

Example:

2024-07-22

Match pattern:

^([0-9]{4})(-?)(1[0-2]|0[1-9])\2(3[01]|0[1-9]|[12][0-9])$

filter

optional

Specifies the filtering to apply to the query.

One of

Rule

allOf {2}

type

enum<string>

required

Specifies that this is a rule.

Allowed value:

rule

dimension

enum<string>

required

The dimension (facet) on which to filter.

Allowed values:

apprenticeship_levelapprenticeship_typecategorycompanycontract_hourscontract_typeeducation_levelindustrylocationoccupationqualificationsalaryseniorityskillskill_tagworkplace_modelyears_of_experience

operator

enum<string>

required

The operator to apply when filtering.

Allowed values:

eqneqgteltegtltanynone

target

required

The filter target type. The type of target depends on the selected dimension.

taxonomy_id

integer

optional

If the dimension is occupation or skill, a taxonomy ID is required.

breakdown

object (Breakdown)

optional

Specifies whether the output should be broken down by a specific dimension.

dimension

enum<string>

required

The dimension (facet) by which to breakdown the results..

Allowed values:

apprenticeship_levelapprenticeship_typecategorycompanycontract_hourscontract_typeeducation_levelindustrylocationoccupationqualificationsalaryseniorityskillskill_tagworkplace_modelyears_of_experience

taxonomy_id

integer

optional

If the breakdown dimension is occupation or skill, a taxonomy ID is required.

location_type_id

integer

optional

If the breakdown dimension is location, a location type ID must be provided.

{
  "metric": "demand",
  "date_range": {
    "type": "absolute",
    "start": "2023-07-19",
    "end": "2024-07-22"
  },
  "filter": {
    "type": "rule",
    "dimension": "apprenticeship_level",
    "operator": "eq",
    "target": {
      "type": "object",
      "id": 0,
      "name": "string"
    },
    "taxonomy_id": 0
  },
  "breakdown": {
    "dimension": "apprenticeship_level",
    "taxonomy_id": 0,
    "location_type_id": 0
  }
}

Request samples

Responses

No response body(200)

HTTP Code: 200

Content Type : JSONapplication/json

metric

enum<string>

required

Specifies which metric (demand or salary) the query was based on.

Allowed values:

demandsalary

key_metrics

object (MetricValue)

required

The aggregated value of the selected metric over the selected date range and filtered by the given rules. Only present if no breakdown dimension was specified in the query.

metric_value

required

An object containing the type and value of the metric.

breakdown_dimension

enum<string>

required

The dimension (facet) by which the results have been broken down.

Allowed values:

apprenticeship_levelapprenticeship_typecategorycompanycontract_hourscontract_typeeducation_levelindustrylocationoccupationqualificationsalaryseniorityskillskill_tagworkplace_modelyears_of_experience

breakdown

array[object (BreakdownResult) {2}]

required

Each object in the array represents the aggregated value of the selected metric, for each result in a breakdown. Only present if a breakdown dimension was specified in the query.

metric_value

required

An object containing the type and value of the metric.

breakdown_value

object (BreakdownValue)

required

An object specifying the a single instance of the breakdown facet.

raw

array[object (RawData) {3}]

required

Each object in the array represents the metric value at a (weekly) point in time in the selected date range. If a breakdown dimension was specified in the query, there may be multiple RawDataObjects for each date, one for each result in the breakdown. The data in this field can be used to plot time series charts.

date

string <date-time>

required

A date-time in ISO 8601 format.

metric_value

required

The value of the metric.

breakdown_value

object (BreakdownValue)

required

The instance of the breakdown dimension (if specified).

Not configured

Last modified: 5 months ago