Every endpoint, its parameters and the fields it returns, generated from the API's own OpenAPI document. Examples use plumbers (5315) and Leeds.
Labour market information for the UK, built entirely from open data: what
occupations pay, how many people work in them, and what the work involves.
Start here. Resolve a job title to an occupation with
/v1/occupations/search?q=…, then use its four-digit SOC 2020 code with the
other endpoints.
Authentication. Send your key in the X-API-Key header. The /v1/meta
endpoints are open.
Before showing any figure, check presentable. Survey estimates vary
in reliability; a figure marked unreliable should not be shown as a number.
Read coverage, which says what a figure counts and when - pay counts
employee jobs, employment counts people including the self-employed. A
figure ONS withholds is null, never zero.
Attribution. The data is free to reuse, but its licences require you to
credit it wherever you show it. For pay, employment and occupations: "Source:
Office for National Statistics licensed under the Open Government Licence
v.3.0". For skills: "This service uses the ESCO classification of the
European Commission". Each response's provenance names the exact release.
This service uses the ESCO classification of the European Commission.
The unit group's title, its place in the SOC 2020 hierarchy, its ISCO-08
mapping, a sample of the job titles classified to it, and in about the
ONS description of the work and its typical tasks.
The international ISCO-08 group this maps to, used to join skills data.
titleCountinteger
How many job titles in the ONS coding index map to this unit group.
examplesarray of string
A sample of those job titles, default titles first.
aboutOccupationAbout or null
What the job involves, in ONS's words. Null until SOC 2020 Volume 1 has been ingested.
3 fields in about
descriptionstring
What people in the occupation do.
tasksarray of string
Typical tasks. Each continues "Job holders in this occupation..." so starts in lower case, e.g. "examines drawings and specifications to determine layout of system".
provenanceProvenance
Where the description came from.
6 fields in provenance
sourcestring
Name of the upstream dataset.
publisherstring
Organisation that publishes it.
licencestring
Licence the data is reused under. Most require attribution; see the attribution guide.
editionstring
The release the figure was taken from, as the publisher labels it, e.g. "2025 provisional".
publisheddate-time or null
When this service began serving that release.
urlstring
The publisher's page for the dataset.
Errors
401The key is missing, unknown or revoked.
404No such occupation or area, or no figure for that combination.
429Rate limit reached; wait for the seconds in Retry-After.
Resolves free text - "plumber", "plumbers mate", even a misspelling - to
SOC 2020 unit groups, using the 32,000 job titles in the ONS coding index.
Results are ranked occupations, not ranked synonyms: each unit group
appears once, with the job title that matched it best. An exact match
always ranks first. The index already separates similar-sounding jobs
that are classified differently, such as a plumber (5315, a skilled
trade) and a plumber's mate (9129, an elementary occupation).
The ONS coding index's job titles for the unit group, in natural word
order, with the qualifier that some carry - "Engineer" in one industry
codes differently from "Engineer" in another. For building search over
job titles; /search does the matching for you.
The full pay distribution - median, mean and percentiles - for one
occupation, area, year and breakdown, from the ONS Annual Survey of Hours
and Earnings. Defaults to gross annual pay for all employees in the UK in
the latest year.
Check presentable before showing a figure, and pass on coverage:
ASHE counts employee jobs only, so it says nothing about self-employed
people in the occupation. Figures are provisional until ONS revises
them the following spring. Any figure ONS withholds is null, never zero.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
measurestring, query
Pay measure. Default annual_pay_gross.
One of weekly_pay_gross, weekly_pay_excl_overtime, basic_pay_incl_other, overtime_pay, hourly_pay_gross, hourly_pay_excl_overtime, annual_pay_gross, annual_pay_incentive, hours_paid_total, hours_paid_basic, hours_paid_overtime
sexstring, query
all, male or female. Default all.
One of all, male, female
patternstring, query
all, fulltime or parttime. Default all.
One of all, fulltime, parttime
yearinteger, query
Reference year. Default the latest published.
editionuuid, query
Pin an exact release by its id from /v1/meta/editions, e.g. to keep figures stable through an academic year. Overrides year.
areastring, query
uk (default), an English region, wales or scotland.
One of uk, wales, scotland, north-east, north-west, yorkshire-and-the-humber, east-midlands, west-midlands, east-of-england, london, south-east, south-west
Median and mean pay for every published year, oldest first. Each point
says whether it is provisional - mark those on a chart, because ONS will
still revise them. Withheld years are included with null values, so a
gap in a chart can be shown as a gap.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
measurestring, query
Pay measure. Default annual_pay_gross.
One of weekly_pay_gross, weekly_pay_excl_overtime, basic_pay_incl_other, overtime_pay, hourly_pay_gross, hourly_pay_excl_overtime, annual_pay_gross, annual_pay_incentive, hours_paid_total, hours_paid_basic, hours_paid_overtime
sexstring, query
all, male or female. Default all.
One of all, male, female
patternstring, query
all, fulltime or parttime. Default all.
One of all, fulltime, parttime
areastring, query
uk (default), an English region, wales or scotland.
One of uk, wales, scotland, north-east, north-west, yorkshire-and-the-humber, east-midlands, west-midlands, east-of-england, london, south-east, south-west
Median pay in each English region, Wales and Scotland, with the UK
figure for the same year and each region's difference from it. Regions
are by workplace - where the job is, not where the employee lives.
Regions ONS withholds are still listed, with a null median, so a map can
show "not published" rather than leave a hole. Northern Ireland is not
published at this level. Regional pay covers annual, weekly and hourly
gross pay.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
measurestring, query
annual_pay_gross (default), weekly_pay_gross or hourly_pay_gross.
One of annual_pay_gross, weekly_pay_gross, hourly_pay_gross
How many people were granted visas to come to the UK to work in the
occupation, from the Home Office's quarterly immigration statistics:
every quarter since Q4 2024, and the latest four quarters broken down by
visa route, nationality and the sponsor's industry, with the occupation's
rank among all occupations.
A measure of how far employers recruit from abroad for the occupation,
not of how many vacancies it has.
The occupation's level in the DfE / Skills England Occupations in Demand
index - critical, elevated or not in high demand - and which of the five
indicators behind it were signalling. previous is the year before,
re-assessed on the same method, so the two can be compared.
Show uncertainty, imputation and capping where present: they are
the publisher's own caveats on this occupation.
The average of the five indicators; higher is more demand. It ranks occupations but does not decide the level. Compare occupations within a year, not across years.
indicatorsarray of DemandIndicator
Each indicator's signal.
3 fields in indicators
indicatorstring
visa_grants, online_job_adverts, wage_growth, wage_premium or hours_worked.
signalstring
"critical", "elevated" or "none".
measuresstring
What the indicator measures.
uncertaintystring or null
The publisher's note on indicators whose data is uncertain, or null if none.
imputationstring or null
The publisher's note on indicators filled in from the occupation's three-digit group for lack of data, or null if none.
cappingstring or null
The publisher's note on indicators held at elevated because they were imputed, or null if none.
onImmigrationSalaryListboolean or null
Whether the occupation was on the Immigration Salary List when assessed.
previousDemandYear or null
The year before, re-assessed by the publisher on the same method, for comparison. Null if there is none.
8 fields in previous
yearinteger
The assessment year.
levelstring
"critical", "elevated" or "not_in_high_demand".
demandIndexnumber or null
The average of the five indicators; higher is more demand. It ranks occupations but does not decide the level. Compare occupations within a year, not across years.
indicatorsarray of DemandIndicator
Each indicator's signal.
3 fields in indicators
indicatorstring
visa_grants, online_job_adverts, wage_growth, wage_premium or hours_worked.
signalstring
"critical", "elevated" or "none".
measuresstring
What the indicator measures.
uncertaintystring or null
The publisher's note on indicators whose data is uncertain, or null if none.
imputationstring or null
The publisher's note on indicators filled in from the occupation's three-digit group for lack of data, or null if none.
cappingstring or null
The publisher's note on indicators held at elevated because they were imputed, or null if none.
onImmigrationSalaryListboolean or null
Whether the occupation was on the Immigration Salary List when assessed.
definitionsstring
What the levels mean and how they are decided.
coverageCoverage
What the assessment covers.
4 fields in coverage
populationstring
What is counted: "employee jobs" or "people in employment".
includesSelfEmployedboolean
Whether self-employed people are included.
referencePeriodstring
The period the figure describes, e.g. "tax year ending 5 April 2025".
notestring
Caveats a consumer should be aware of when presenting the figure.
provenanceProvenance
Where it came from.
6 fields in provenance
sourcestring
Name of the upstream dataset.
publisherstring
Organisation that publishes it.
licencestring
Licence the data is reused under. Most require attribution; see the attribution guide.
editionstring
The release the figure was taken from, as the publisher labels it, e.g. "2025 provisional".
publisheddate-time or null
When this service began serving that release.
urlstring
The publisher's page for the dataset.
Errors
401The key is missing, unknown or revoked.
404No such occupation or area, or no figure for that combination.
429Rate limit reached; wait for the seconds in Retry-After.
How many vacancies employers had in the occupation, how many were hard to
fill, and how many were hard to fill because applicants lacked the skills -
the standard measure of a skill shortage. From the Employer Skills Survey.
The survey withholds figures based on fewer than 30 employers, which rules
out most four-digit occupations. The response uses the finest level the
survey published - the occupation itself where possible, otherwise its
minor, sub-major or major group - and group and derivation say which.
allOccupations gives the same measures for the whole economy for comparison.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
areastring, query
uk (default) or a nation. The survey does not publish occupation figures for English regions.
One of uk, england, wales, scotland, northern-ireland
The occupation's workforce by age band, by highest qualification and by
industry, from the Annual Population Survey, with headline shares: aged
under 25, aged 55 and over, and holding a degree.
Each figure carries a quality band. Show acceptable figures with a
caution and never show unreliable ones, which ONS withheld.
How many people work in the occupation, how that has changed year by
year, and who they are - the shares who are women, part-time and
self-employed - from the ONS Annual Population Survey.
Available for the UK and each nation only; the breakdown is UK-only and
null for a nation. These figures count people, including the
self-employed, so they differ from the job counts that accompany pay.
notes flags when a large self-employed share means pay figures describe
only part of the occupation - worth passing on to users.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
areastring, query
uk (default), england, wales, scotland or northern-ireland.
One of uk, england, wales, scotland, northern-ireland
Whether the occupation's broad group is projected to grow or shrink to
2035, and how many job openings it is expected to have - from growth and
from replacing people who retire or leave. Openings are usually large
even for a shrinking group, which is often the more useful message.
From the Department for Education's projections (The Skills Imperative
2035). They exist only for SOC 2020 sub-major groups, each covering about
sixteen occupations, so the figures are for the occupation's group and
derivation says which. They are modelled trends, not forecasts; pass on
accuracy. Figures for a group under 10,000 jobs in an area are null
and marked not presentable: the publisher asks users not to publish them. Wherever the
figures are shown, the publisher requires citation.
byQualification splits the outlook by the highest qualification
workers hold, so you can say which levels the openings are for. These
cells are smaller and so more often below the 10,000 threshold,
particularly in regions.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
areastring, query
uk (default), a nation, or an English region.
One of uk, england, wales, scotland, northern-ireland, north-east, north-west, yorkshire-and-the-humber, east-midlands, west-midlands, east-of-england, london, south-east, south-west
How many new job adverts appeared online for the occupation each month
since January 2017, from ONS's labour demand volumes, with the latest
twelve months totalled, compared with the twelve before, and ranked
against every other occupation.
ONS has suppressed some recent months after source problems; those are
null and left out of totals, and monthsSuppressed says how many. Show
notices alongside any recent figures.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
areastring, query
uk (default), a nation, or an English region.
One of uk, wales, scotland, north-east, north-west, yorkshire-and-the-humber, east-midlands, west-midlands, east-of-england, london, south-east, south-west
New adverts over the months ONS published. Lower than the true total when any month is suppressed.
monthsSuppressedinteger
Months in the period ONS suppressed, which adverts leaves out.
averagePerMonthnumber or null
Average new adverts per published month. Compare occupations on this rather than adverts, since ONS suppresses different months for different occupations.
changePercentnumber or null
Change on the twelve months before, comparing only months published in both periods. Null if there are none.
rankinteger
The occupation's rank by averagePerMonth among all occupations in the area, 1 being the most.
occupationsRankedinteger
Occupations ranked.
monthsarray of JobAdvertMonth
Every month since January 2017, oldest first.
2 fields in months
monthstring
"2026-08".
advertsinteger or null
Adverts that first appeared online in the month. Null where ONS suppressed the month for quality.
noticesarray of JobAdvertNoticeItem
ONS's data quality notices for this release. Show them alongside recent months.
2 fields in notices
headingstring
e.g. "Data issue - March 2026".
textstring
What ONS said.
coverageCoverage
What the figures count.
4 fields in coverage
populationstring
What is counted: "employee jobs" or "people in employment".
includesSelfEmployedboolean
Whether self-employed people are included.
referencePeriodstring
The period the figure describes, e.g. "tax year ending 5 April 2025".
notestring
Caveats a consumer should be aware of when presenting the figure.
provenanceProvenance
Where they came from.
6 fields in provenance
sourcestring
Name of the upstream dataset.
publisherstring
Organisation that publishes it.
licencestring
Licence the data is reused under. Most require attribution; see the attribution guide.
editionstring
The release the figure was taken from, as the publisher labels it, e.g. "2025 provisional".
publisheddate-time or null
When this service began serving that release.
urlstring
The publisher's page for the dataset.
Errors
400A parameter is invalid; the detail lists the valid values.
401The key is missing, unknown or revoked.
404No such occupation or area, or no figure for that combination.
429Rate limit reached; wait for the seconds in Retry-After.
Every local area with new online job adverts for the occupation over the
latest four quarters, most first. perThousand is the occupation's share
of all adverts in the area, and concentration compares it with the
UK: above 1 means the occupation is more in evidence there than nationally.
New online job adverts for the occupation in the area each quarter for
the last three years, the latest four quarters totalled and compared
with the four before, and the occupation's rank among all occupations
advertised there.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
areastring, in the pathRequired
A local authority's GSS code or slug, e.g. "leeds". See /v1/local-areas.
One of uk, wales, scotland, north-east, north-west, yorkshire-and-the-humber, east-midlands, west-midlands, east-of-england, london, south-east, south-west
Skills and knowledge from ESCO, the European Commission's classification,
joined to the SOC unit group through its ISCO-08 code. Skills are pooled
across every related ESCO occupation and ranked by how many of them list
each one, so the top of the list is what the work broadly involves.
These are related occupations rather than exact equivalents - several UK
unit groups can share one ISCO-08 group. The derivation field says how
the match was made; pass that on when presenting the results.
The career interest profile (Holland's six RIASEC types) and the abilities
the work calls on, for matching people to occupations. No UK source
publishes these, so they come from the US O*NET database.
ONET describes American occupations. They are reached through ISCO-08
and the official ESCO to ONET crosswalk, which usually links a UK
occupation to several US ones; the profile is their weighted average.
basedOn lists them - show it, so users can judge the match - and
derivation explains it. Wherever the profile is shown, O*NET's licence
requires the attribution text.
The routes into the occupation as the National Careers Service describes
them: university, college, apprenticeship, working your way up,
volunteering, applying directly - each with its entry requirements -
and what you will need, such as background checks or a licence.
The careers service writes profiles per job, not per SOC unit group, so
an occupation can have several (plumbers: plumber, heating engineer and
others) or none. Each is matched to a unit group through the ONS coding
index by its title or an alternative title; match says which.
The occupations on Skills England's occupational maps that sit behind
the SOC unit group, each with its apprenticeship standards, T Levels and
other technical qualifications. A unit group usually has several:
plumbers (5315) cover gas engineering operatives, heating engineers,
plumbing and domestic heating technicians and more.
match says whether Skills England codes the occupation to this unit
group (primary) or mainly to another, partly to this one (partial).
Retired and withdrawn apprenticeships are left out unless
includeInactive=true.
Skills England's terms require its logo and the attribution statement
wherever this data is shown.
Parameters
socstring, in the pathRequired
Four-digit SOC 2020 unit group code.
includeInactiveboolean, query
Include retired and withdrawn apprenticeships. Default false.
Every assessed occupation at the given level in the latest year, highest
demand index first. Without level, the occupations in critical and
elevated demand.
When each source was last checked for new releases, and any release
currently held back because it failed validation - in which case the
previous release is still being served. Never cached. No API key needed.
Example
curl "https://api.jobfacts.uk/v1/meta/ingest"
Response IngestStatusResponse
Show the 2 fields
sourcesarray of SourceFreshness
Last check per source.
3 fields in sources
sourceKeystring
Which source.
lastRundate-time
Most recent check.
lastSuccessdate-time or null
Most recent check that did not fail.
quarantinedarray of QuarantinedEdition
Releases currently held back.
4 fields in quarantined
iduuid
Edition id.
sourceKeystring
Which source.
labelstring
The publisher's name for the release.
detectedAtdate-time
When it was seen.
Errors
429Rate limit reached; wait for the seconds in Retry-After.
The history of every release ingested, newest first, including any held
back by validation (quarantined) and any that published with a known
issue (see checks). Pass a release's id as ?edition= to the pay
endpoint to pin figures to it. No API key needed.
Parameters
sourcestring, query
Limit to one source key, e.g. ashe_t14.
Example
curl "https://api.jobfacts.uk/v1/meta/editions"
Response array of EditionResponse
Show the 9 fields
iduuid
Pass as ?edition= on the pay endpoint to pin figures to this release.
sourceKeystring
Which source.
labelstring
The publisher's name for the release.
seriesKeystring or null
For pay, the reference year. Releases only replace others in the same series.
statusstring
published, superseded, quarantined, or an in-progress state.
detectedAtdate-time
When the release was first seen.
publishedAtdate-time or null
When it began being served.
sourceUristring
Where it was retrieved from.
checksarray of EditionCheck
Checks that warned or failed. Empty for a clean release.
3 fields in checks
rulestring
Name of the check.
statusstring
"warn" (published with a known issue) or "fail" (held back).
observedstring or null
What the check found.
Errors
429Rate limit reached; wait for the seconds in Retry-After.
Emails a confirmation link to the address. Opening the link and
confirming issues the key. The response is the same whether or not the
address already has a key, and the link replaces any earlier key, which
is also how to recover a lost one. No key is needed to call this.