Reading the figures

Every number in this API is a survey estimate. Some are solid; some rest on a handful of responses. The API tells you which is which, and what each figure actually counts. This page explains how to read those signals - please read it before you show figures to anyone, particularly young people making decisions about careers.

Quality and presentable

Every pay and employment figure carries a quality band and a presentable flag.

The bands are the ones ONS uses in its own earnings tables.

If presentable is false, do not show the figure as a number. Show "not enough data" or similar. The figure is returned anyway, so you can make that decision yourself and so a table does not silently lose a row.

The two sources behave differently:

• Pay (ASHE): ONS suppresses any pay estimate with a CV above 20% before publishing it. So a published pay figure is never unreliable. About one published figure in eight has no CV given; those are graded acceptable, the lowest band ONS would publish.
• Employment (APS): the survey publishes estimates from very small samples and flags them rather than withholding them. These are where unreliable most often appears - for example, the share of women in a male-dominated trade.

null means withheld, never zero

When ONS withholds a figure - because it is too uncertain, or because publishing it could identify someone - the API returns null. A null salary is not a salary of zero. Show it as "not available".

Common examples: the 90th percentile of pay in well-paid occupations, pay for a small occupation in a small region, and the breakdown of employment for a nation.

Provisional figures

ONS publishes each year's pay figures twice: provisional in the autumn, and revised the following spring. Until the revision lands, pay responses say "provisional": true, and so does each provisional point of a pay series.

Mark provisional figures as such, especially on charts, where the latest point is usually provisional and the others are not.

Two surveys, two different counts

Pay and employment come from different surveys, and they count different things. Every response has a coverage block saying which.

So for plumbers, the pay endpoint reports about 53,000 full-time employee jobs and the employment endpoint reports 153,700 people. Both are right.

Two consequences matter in practice:

• Pay figures do not describe the self-employed. Where a large share of an occupation is self-employed, the employment endpoint adds a note saying so. For plumbers it is nearly half.
• ASHE job counts are indicative only. ONS says they should not be treated as accurate estimates. Use the employment endpoint for headcounts.

Projections: modelled trends, not forecasts

/projections answers "is this work growing?" from the Department for Education's projections to 2035. Read them differently from everything else:

• They are for a broad group, not the occupation. Projections exist only for 26 occupation groups. A plumber gets the figures for skilled construction and building trades, twelve occupations together. derivation says which group; individual occupations within it can do better or worse.
• They are modelled. Up to 2020 the figures are the modellers' historical estimates; from 2021 they are projections made in 2021/22, including years that have since passed. Each point in series says which. For actual recent employment, use /employment.
• They are not precise. The publisher calls them indicative of general trends and orders of magnitude. In its own review of earlier rounds, occupational employment was typically projected within 7% over five to ten years, and the direction of change was right about 80% of the time. accuracy says this; pass it on.
• They count jobs, at the workplace, including self-employment - a third measure, different from both the pay and the employment counts below.
• Figures under 10,000 are marked presentable: false, following the publisher's guidance. Everything is rounded to the nearest 1,000, and a change under 1,000 is reported as "little change".

byQualification splits the outlook by the highest qualification workers hold, so you can say which levels the openings are for. Two things to know:

• A level can have negative requirement. Qualification levels across the workforce are rising, so lower levels are often projected to shrink faster than people leave. For health professionals, nursing qualifications at RQF 5 are being replaced by degrees. A negative figure means fewer such workers will be needed, not that there are no openings.
• The cells are smaller, so more fall below the 10,000 threshold and are marked presentable: false, especially in the regions.

The most useful figure is often totalRequirement: the new workers a group will need from both growth and replacing people who retire or leave. It is usually large even where a group is shrinking. Administrative occupations are projected to shrink by 12% to 2035, yet still need around a million new workers.

Demand: is the occupation in demand?

/demand gives the occupation's level in the DfE and Skills England Occupations in Demand index: critical, elevated or not_in_high_demand. It rests on five indicators, each compared with its own usual level:

• visa_grants - work visas granted, relative to employment;
• online_job_adverts - adverts relative to employment;
• wage_growth - the year's change in hourly pay;
• wage_premium - pay against occupations at the same skill level;
• hours_worked - the year's change in weekly hours.

Each indicator's signal is critical (a standard deviation or more above usual), elevated (above usual) or none. The level follows from how many signal and how strongly. It takes four elevated indicators, or one critical, to reach elevated, so plumbers, with three elevated, are not in high demand. definitions gives the full rule.

demandIndex averages the five and ranks occupations within a year. It does not decide the level, and it does not compare across years.

Pass on uncertainty, imputation and capping when they are present. They are the publisher's caveats: uncertainty because, say, many workers are self-employed and so missing from the pay data, or indicators filled in from the broader three-digit group for lack of data. /v1/demand lists the occupations at a level, highest index first, for pages like "jobs in demand".

Workforce: who does the job

/workforce describes the people in the occupation: their age bands, their highest qualification and the industries that employ them, from the Annual Population Survey. The headline shares answer common careers questions:

• aged55AndOverPercent - a quarter of plumbers are 55 or over, so many will retire over the next decade and need replacing;
• agedUnder25Percent - how many people start young;
• degreePercent - 95% of GPs hold a degree, against 7% of plumbers.

There are no confidence intervals here. Figures ONS shaded as small-sample come back acceptable. Show them with a caution. Withheld ones come back unreliable with people: null. A headline share is null whenever one of the bands it needs was withheld, rather than being understated.

How to become: routes in from the National Careers Service

/how-to-become returns the National Careers Service's job profiles for the occupation. Most occupations have one, and some have several: plumbers (5315) have plumber, heat pump engineer, kitchen and bathroom fitter, and gas service technician. Each profile lists its routes, which are university, college, apprenticeship, work (working your way up), volunteering, direct_application, other_routes and more_information (registration, professional bodies, career tips). Each route holds headed blocks of paragraphs and lists in page order. Look for the block headed "Entry requirements".

requirements holds what you will need regardless of route, such as "pass enhanced background checks" or "have a full driving licence".

match says how the profile was tied to the unit group: by its own title or by an alternative title. Show the profile's title alongside its content, since it may be a narrower job than the unit group.

Apprenticeships: routes in through technical education

/apprenticeships lists the occupations on Skills England's occupational maps that sit behind the unit group. These are the occupations that apprenticeships and T Levels are built around, and a unit group usually has several. Plumbers (5315) cover gas engineering operatives, gas network craftspeople, low carbon heating technicians, and plumbing and domestic heating technicians. Each comes with its products:

• apprenticeship standards, with their level and status;
• foundation_apprenticeship and apprenticeship_unit - shorter routes;
• t_level - two-year courses for 16 to 19 year olds;
• higher_technical_qualification and technical_qualification.

Each apprenticeship standard also has a detail object, from Skills England's apprenticeship standards. It gives the typical durationMonths, any entryRequirements, the statutory regulator in regulatedBy (the General Medical Council for the doctor apprenticeship, for example), and any professionalRecognition it leads to. degree says whether it includes a degree, and qualificationsGained lists what you come away with. Most standards leave entry requirements to the employer, so entryRequirements is usually null.

The headline figures, apprenticeshipsAvailable and lowestApprenticeshipLevel, count only primary matches and only standards approved for delivery. They answer "can I get into this through an apprenticeship, and from what level?" Show the Skills England logo and attribution alongside.

Job adverts: how much employers are hiring

/job-adverts counts new online job adverts for the occupation each month since January 2017, for the UK (default), a nation or an English region. latestYear sums the last twelve months, ranks the occupation against every other in the area, and gives changePercent on the year before.

Three things to know:

• Some recent months are null. ONS suppressed them after a source dropped out. They are left out of adverts, and monthsSuppressed says how many. changePercent compares only months published in both years, so a missing month cannot pass for a fall.
• Read trends, not single months. ONS warns that months since late 2025 are more uncertain, and some were imputed. Show notices near any recent figures.
• Compare on the averages. ONS suppresses different months for different occupations, so adverts (a sum) is not like for like. Rankings use averagePerMonth, the average over published months, and so should you.
• Adverts are not vacancies. One advert can be for several jobs, and many jobs are never advertised online. Occupations that recruit through agencies and job boards, such as care and sales, come out high.

Local job adverts

The same release counts adverts by local authority each quarter. Two endpoints read it from the occupation's side:

• /job-adverts/local lists every area with adverts for the occupation, most first;
• /job-adverts/local/{area} gives one area's last twelve quarters, the change on the year before, and the occupation's rank among everything advertised there.

/v1/local-areas/{area}/job-adverts reads it from the area's side: the occupations most advertised in, say, Leeds. Areas take a GSS code or a slug from /v1/local-areas.

Two figures show where an occupation is concentrated:

• perThousand - the occupation's adverts per 1,000 of all adverts in the area;
• concentration - that share against the UK's. 2 means the occupation makes up twice as large a share of adverts there as nationally. Plumbing adverts are 2.2 times as concentrated in Dartford as across the UK.

Both use only quarters published for the occupation and the area's total alike, so suppression on one side cannot skew them. Rankings use averagePerQuarter, for the same reason as the national figures.

Work visas: recruitment from abroad

/visas counts the people granted a visa to come to the UK for a sponsored job in the occupation, each quarter since Q4 2024. latestYear sums the last four quarters and ranks the occupation against every other. It also breaks the total down by route, by nationality (top ten) and by the sponsor's industry (top five).

Read the route before the rank. Farm workers top the list because of the Seasonal Worker route, which brings in short-term harvest labour. That is a different thing from doctors on the Health and Care Worker route. Policy also moves these numbers more than demand does. Care worker visas fell from about 1,700 in Q4 2024 to almost none by 2026, after overseas recruitment of care workers closed in July 2025. The figures say how much employers recruit from abroad, not how many vacancies there are. For demand, use /demand.

provisional: true marks quarters the Home Office will revise.

Vacancies: skill shortages

/vacancies comes from the Employer Skills Survey, which asks employers about the vacancies they have open. It gives three counts, each a subset of the last:

• vacancies - all of them;
• hard to fill - those the employer said were proving hard to fill;
• skill shortage - hard-to-fill vacancies where the reason was applicants lacking skills, qualifications or experience, rather than pay, hours or location.

skillShortagePercent, the share of a group's vacancies that are skill shortages, is the usual headline. Compare it with allOccupations - 27% of all UK vacancies in 2024. Plumbers were at 39%.

The counts are a snapshot at interview, not a year's hiring, and they are small for most occupations: the survey withholds anything based on fewer than 30 employers. So most occupations get a broader group's figures, and derivation says so. The survey runs every two years; previous gives the last one at the same level.

Work profiles: a US guide to the kind of work

/work-profile describes who an occupation suits: its interest profile and the abilities it calls on. No UK source publishes these, so they come from the US O*NET database.

• Interests use Holland's six types - Realistic, Investigative, Artistic, Social, Enterprising, Conventional - scored 1 to 7. hollandCode is the top three, e.g. "RCI" for plumbers. Careers tools and interest quizzes commonly use these codes for matching.
• Abilities are scored 1 to 5 by importance to the work.
• They describe American jobs, averaged. A UK occupation usually maps to several US ones, and the scores are their weighted average. basedOn lists them: for UK plumbers, a quarter of the weight is US septic tank servicers. Use the profile as a guide to the kind of work, and show basedOn so users can see where it came from.

Reference periods

referencePeriod says exactly what period a figure describes. Pay depends on the measure:

• weekly and hourly pay: "pay period including a date in April 2025"
• annual pay: "tax year ending 5 April 2025"

Employment periods are twelve-month windows such as "Apr 2025-Mar 2026". The employment series uses calendar years ("Jan 2024-Dec 2024").

Editions and pinning

Each release of each dataset is an edition. When a new edition is published, the API serves it by default and keeps the old one.

To keep figures stable - for example through an academic year, so a course page does not change under a student - pin the edition. Find its id with /v1/meta/editions and pass ?edition= to the pay endpoint.

/v1/meta/editions also shows releases that were held back because they failed validation (quarantined), and any published with a known issue (in checks). If an occupation unexpectedly returns nothing, check there.

Provenance

Every data response carries a provenance block: the dataset, publisher, licence, edition and a link. Use it to attribute what you show - see Attribution.