jobfacts

Getting started

A key, a first request, and the calls most integrations need.

Getting started

1. Get a key

Keys are free. Get one with your email address: we send a link, and the link shows your key, once. Lost it? Ask again; the new key replaces the old one.

Send the key in the X-API-Key header on every request except those under /v1/meta, which are open so you can see what the service covers before you have a key. Call the API from your server, not from code that runs in a browser or app, where anyone could read the key.

export LMI_API=https://...   # the base address on the developers overview
export LMI_KEY=lmi_...

2. Find the occupation

Everything in the API is keyed on a four-digit SOC 2020 code - the UK's standard occupational classification. You will rarely know the code; start from a job title.

curl -H "X-API-Key: $LMI_KEY" "$LMI_API/v1/occupations/search?q=plumber&limit=3"

[
  { "soc2020": "5315", "title": "Plumbers and heating and ventilating installers and repairers",
    "matchedTitle": "Plumber", "qualifier": null, "confidence": 1, "matchType": "exact" },
  { "soc2020": "9129", "title": "Elementary construction occupations n.e.c.",
    "matchedTitle": "Plumber's mate", "qualifier": null, "confidence": 0.47, "matchType": "fuzzy" },
  { "soc2020": "5242", "title": "Telecoms and related network installers and repairers",
    "matchedTitle": "Plumber and jointer", "qualifier": null, "confidence": 0.42, "matchType": "fuzzy" }
]

Search tolerates misspellings and possessives ("plumer", "plumbers mate"), and keeps apart jobs that sound alike but are classified differently: a plumber is a skilled trade (5315), a plumber's mate an elementary occupation (9129). If you are taking a title from a user, show them the top few matches rather than silently taking the first. See Occupations and areas.

3. What does it pay?

curl -H "X-API-Key: $LMI_KEY" "$LMI_API/v1/occupations/5315/pay?pattern=fulltime"

{
  "soc2020": "5315",
  "area": { "code": "K02000001", "slug": "uk", "name": "United Kingdom" },
  "year": 2025,
  "referencePeriod": "tax year ending 5 April 2025",
  "provisional": true,
  "measure": "annual_pay_gross",
  "unit": "gbp_per_year",
  "workPattern": "fulltime",
  "mean": 38337,
  "distribution": { "p10": 24916, "p25": 31656, "median": 37881, "p75": 45451, "p90": null },
  "quality": "precise",
  "presentable": true,
  "coverage": { "population": "employee jobs", "includesSelfEmployed": false, "...": "..." },
  "provenance": { "source": "ASHE Table 14: ...", "licence": "OGL v3", "edition": "2025 provisional", "...": "..." }
}

Four things to notice, all covered in Reading the figures:

  • Use the median, not the mean. A few high earners pull the mean up.
  • p90 is null, not zero. ONS withheld it. Never treat a null as zero.
  • provisional: true - ONS will revise this figure next spring.
  • coverage - this is employee jobs only. Self-employed plumbers are not in it.

Add ?area=london for a region, or call /pay/regions to see every region against the UK at once. /pay/series gives the figure year by year.

4. How many people do it, and who?

curl -H "X-API-Key: $LMI_KEY" "$LMI_API/v1/occupations/5315/employment"

{
  "period": "Apr 2025-Mar 2026",
  "employment": { "count": 153700, "confidenceInterval": 15200, "quality": "reasonable",
                  "presentable": true, "shareOfAllEmploymentPercent": 0.46 },
  "breakdown": {
    "female":       { "count": 2800,  "percent": 1.8,  "quality": "unreliable", "presentable": false },
    "partTime":     { "count": 10500, "percent": 6.8,  "quality": "acceptable", "presentable": true },
    "selfEmployed": { "count": 72500, "percent": 47.2, "quality": "reasonable", "presentable": true }
  },
  "notes": [
    "47% of people in this occupation are self-employed. Pay figures from ASHE cover employees only, so they do not describe that group."
  ]
}

Two things worth showing your users:

  • The female share is presentable: false - the survey sample is too small. Show something like "too few to estimate", not "1.8%".
  • The note. Nearly half of plumbers are self-employed, so the pay figures in step 3 describe only about half of them. This API tells you that; most sources of salary data do not.

The headcount (153,700 people) and the pay endpoint's job count (about 53,000) are not in conflict: one counts people including the self-employed, the other counts full-time employee jobs. See Reading the figures.

5. What does the work involve?

curl -H "X-API-Key: $LMI_KEY" "$LMI_API/v1/occupations/5315/skills?limit=5"

Returns related roles (bathroom fitter, gas service technician, heating engineer...) and the skills and knowledge they share, most widely shared first, from the European Commission's ESCO classification. The derivation field explains the match - these are related occupations, not exact equivalents - and you should pass that on.

6. Is the work growing?

curl -H "X-API-Key: $LMI_KEY" "$LMI_API/v1/occupations/5315/projections"

{
  "group": { "code": "53", "title": "Skilled construction and building trades", "unitGroups": 12 },
  "outlook": {
    "baseYear": 2020, "targetYear": 2035,
    "employmentBase": 903000, "employmentTarget": 889000,
    "netChange": -14000, "netChangePercent": -1.5, "direction": "declining",
    "replacementDemand": 388000, "totalRequirement": 374000,
    "presentable": true
  },
  "citation": "Source: The Skills Imperative 2035 (2024), NFER/Nuffield/DfE/IER/CE, https://www.gov.uk/..."
}

The construction trades are projected to shrink slightly, but to need 374,000 new workers by 2035 to replace people retiring or leaving. These are figures for the whole group of twelve occupations, and modelled trends rather than forecasts - see Reading the figures. Show citation wherever you use them.

7. Before you go live

  • Read Attribution. Showing this data without it breaches the licences it is published under.
  • Handle presentable: false and null values in your UI.
  • Expect 429 responses under load; they say when to retry. See Errors, limits and freshness.