Economics API Reference

UK economic series from ONS and monthly HMRC tax receipts, NICs, and administered expenditure.

Base URL: https://api.govdata.dev/v1

HMRC Tax Receipts

Returns every receipts and expenditure series published by HMRC. Monthly data runs from April 2017; annual financial-year totals run from 2006–07. Amounts are integer £ million; unavailable [X] cells are omitted and provisional observations are flagged.

GET /v1/economics/tax-receipts

Parameters

Name	Type	Required	Default	Description
`head_of_duty`	string	No	—	Duty key such as income_tax, national_insurance_contributions, or child_benefit_payments
`frequency`	string	No	—	monthly (default) or annual
`from_period`	string	No	—	YYYY-MM for monthly or YYYY-YY for annual
`to_period`	string	No	—	Inclusive end period in the matching format

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.govdata.dev/v1/economics/tax-receipts?head_of_duty=income_tax&from_period=2026-06&to_period=2026-06"

Response

{"data":[{"period":"2026-06","head_of_duty":"income_tax","label":"Income Tax","category":"receipt","amount":23811,"unit":"£ million","provisional":true}],"meta":{"source":"HM Revenue & Customs","source_url":"https://www.gov.uk/government/statistics/hmrc-tax-and-nics-receipts-for-the-uk","licence":"Open Government Licence v3.0","api_version":"v1","unit":"£ million","coverage":{"from":"2017-04","to":"2026-06"}},"pagination":{"total":1,"page":1,"per_page":25,"total_pages":1}}

Requests wholly outside data-derived coverage return 404 period_not_covered. Source workbook (NS_Table.ods, updated monthly): HMRC tax and NICs receipts for the UK.

Error responses

{"error":{"code":"invalid_period","message":"Periods must use YYYY-MM for monthly data or YYYY-YY for annual data.","documentation_url":"https://docs.govdata.dev/errors/invalid_period"}}

{"error":{"code":"period_not_covered","message":"Requested period 2026-07 is outside dataset coverage 2017-04 to 2026-06.","documentation_url":"https://docs.govdata.dev/errors/period_not_covered"}}

Invalid periods, frequency, or reversed ranges return 422. A wholly uncovered range returns 404. HMRC updates the workbook monthly and can revise recent provisional values; figures are receipts recorded by HMRC, not accrual-based tax liabilities.

Monthly Trade in Goods

GET /v1/economics/trade

Returns monthly UK overseas trade statistics aggregated by HS2 commodity chapter, partner country, and EU/non-EU import or export flow. Use it for trade dashboards and commodity or market analysis; no trader or transaction data is exposed.

GET /v1/economics/trade

Parameters

Name	Type	Required	Default	Description
`month`	string	No	—	Optional month in YYYY-MM or YYYYMM format; must fall inside loaded OTS coverage.
`hs2`	string	No	—	Exact HS2 chapter, zero-padded to two digits. Suppressed and below-threshold rows use unallocated.
`country`	string	No	—	Exact alpha code, case-insensitive country name, or numeric uktradeinfo country ID.
`flow`	string	No	—	One of eu_import, eu_export, non_eu_import, or non_eu_export.
`page`	integer	No	1	One-based results page.
`per_page`	integer	No	25	Results per page, maximum 100.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.govdata.dev/v1/economics/trade?month=2024-01&hs2=01&country=FR&flow=eu_import"

Response

{"data":[{"month_id":202401,"flow":"eu_import","hs2":"01","hs2_description":null,"country_id":7,"country_code":"FR","country_name":"France","value_gbp":12345,"net_mass_kg":"42.5"}],"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"HMRC uktradeinfo","source_url":"https://www.uktradeinfo.com/api-documentation/","value_unit":"whole pounds sterling","net_mass_unit":"kilograms"},"pagination":{"total":1,"page":1,"per_page":25,"total_pages":1}}

Example values come from the trade controller/importer fixture. The development trade tables are currently empty.

Coverage begins January 2000 and is imported from HMRC uktradeinfo when new months appear. Values are whole pounds; net mass is kilograms and can be null. OGL v3.0 applies. HMRC may revise recent periods, and unallocated rows preserve suppressed or below-threshold totals.

Error responses

422 Unprocessable Entity — month is not YYYY-MM or YYYYMM.

{"error":{"code":"invalid_parameter","message":"month must be YYYY-MM or YYYYMM","documentation_url":"https://docs.govdata.dev/errors/invalid_parameter"}}

404 Not Found — the requested month is outside loaded coverage.

{"error":{"code":"not_found","message":"Trade data does not cover 199912; available period is 202401 to 202401.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Regional Trade in Goods

GET /v1/economics/trade/regional

Returns Regional Trade Statistics aggregated by UK region, partner-country group, and flow. Use it to compare the trade profile of UK nations and English regions without exposing businesses or individual declarations.

GET /v1/economics/trade/regional

Parameters

Name	Type	Required	Default	Description
`month`	string	No	—	Optional RTS reference month in YYYY-MM or YYYYMM format.
`region`	string	No	—	Exact uppercase region code or numeric uktradeinfo region ID.
`country_group`	string	No	—	Exact partner-country grouping published in RTS.
`flow`	string	No	—	One of eu_import, eu_export, non_eu_import, or non_eu_export.
`page`	integer	No	1	One-based results page.
`per_page`	integer	No	25	Results per page, maximum 100.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.govdata.dev/v1/economics/trade/regional?month=2024-01&region=UKC&country_group=Asia&flow=non_eu_export"

Response

{"data":[{"month_id":202401,"flow":"non_eu_export","region_id":1,"region_code":"UKC","region_name":"North East","country_id":9,"country_group":"Asia","value_gbp":50,"net_mass_kg":null}],"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"HMRC uktradeinfo","source_url":"https://www.uktradeinfo.com/api-documentation/","value_unit":"whole pounds sterling","net_mass_unit":"kilograms"},"pagination":{"total":1,"page":1,"per_page":25,"total_pages":1}}

Example values come from the regional trade importer fixture. The development regional-trade table is currently empty.

Coverage begins January 2013 and follows HMRC's RTS publication cycle. OGL v3.0 applies. Regional estimates are allocated using trader and employment information, so they are not a direct measure of goods physically entering or leaving a region.

Error responses

422 Unprocessable Entity — month is not YYYY-MM or YYYYMM.

{"error":{"code":"invalid_parameter","message":"month must be YYYY-MM or YYYYMM","documentation_url":"https://docs.govdata.dev/errors/invalid_parameter"}}

404 Not Found — the requested month is outside loaded regional coverage.

{"error":{"code":"not_found","message":"Trade data does not cover 201212; available period is 202401 to 202401.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Inflation Time Series

GET /v1/economics/inflation/:metric

Historical inflation observations for a given metric. Returns monthly data points with optional date range filtering.

Parameters

Parameter	Type	Required	Description
`metric`	string (path)	Yes	`cpi`, `cpih`, or `rpi`
`from`	string (query)	No	Start date in `YYYY-MM` format
`to`	string (query)	No	End date in `YYYY-MM` format

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.govdata.dev/v1/economics/inflation/cpi?from=2024-01&to=2024-06"

Response

{
  "data": {
    "metric": "cpi",
    "name": "Consumer Prices Index",
    "observations": [
      { "date": "2024-01", "value": 4.0, "index": 131.5 },
      { "date": "2024-02", "value": 3.4, "index": 131.8 },
      { "date": "2024-03", "value": 3.2, "index": 132.0 },
      { "date": "2024-04", "value": 2.3, "index": 132.5 },
      { "date": "2024-05", "value": 2.0, "index": 132.8 },
      { "date": "2024-06", "value": 2.0, "index": 132.9 }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "Office for National Statistics",
    "source_url": "https://www.ons.gov.uk/economy/inflationandpriceindices"
  }
}

Error responses and data notes

{"error":{"code":"invalid_parameter","message":"Invalid metric 'unknown'. Valid metrics: cpi, cpih, rpi.","documentation_url":"https://docs.govdata.dev/errors/invalid_parameter"}}

An unknown metric or malformed date returns 400; a valid range without observations returns an empty 200 response. ONS inflation series are updated after their monthly release and may be revised. CPI/CPIH coverage begins in 1989 and RPI in 1948; all are OGL v3.0 and should not be treated as interchangeable measures.

Latest Observation

GET /v1/economics/inflation/:metric/latest

Returns the most recent published observation for the given metric.

Parameters

Parameter	Type	Description
`metric`	string (path)	`cpi`, `cpih`, or `rpi`

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/economics/inflation/cpi/latest

Response

{
  "data": {
    "dataset_id": "cpi",
    "dataset_name": "Consumer Prices Index (CPI)",
    "unit": "percent",
    "time_period": "2025 FEB",
    "date": "2025-02-01",
    "value": 2.8,
    "geography": "K02000001"
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "Office for National Statistics",
    "source_url": "https://www.ons.gov.uk/economy/inflationandpriceindices"
  }
}

Error responses and data notes

{"error":{"code":"not_found","message":"No data available for cpi.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Unknown metrics return 400 and a valid metric with no loaded observation returns 404. Cadence, coverage, ONS attribution, OGL v3.0 licensing, and revision caveats match the inflation time-series endpoint.

Economic Indicators

GET /v1/economics/indicators/:metric

metric * — Economic indicator

from — Start date (YYYY-MM)

to — End date (YYYY-MM)

response

Waiting for request...

Historical economic indicator data. Returns time series observations with optional date range filtering.

GDP quarterly growth

The gdp metric contains 284 quarterly GDP observations from 1955 Q2 to 2026 Q1. It is the ONS IHYQ headline quarter-on-quarter growth series, seasonally adjusted, in percent.

Captured from the reset development API after the 6 August 2026 ONS import:

{
  "data": {
    "dataset_id": "gdp",
    "dataset_name": "Gross Domestic Product (quarterly growth)",
    "unit": "percent",
    "observations": [
      { "time_period": "2026 Q1", "date": "2026-01-01", "value": 0.6, "geography": "K02000001" },
      { "time_period": "2025 Q4", "date": "2025-10-01", "value": 0.2, "geography": "K02000001" }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "ONS",
    "source_url": "https://www.ons.gov.uk"
  },
  "pagination": { "total": 5, "page": 1, "per_page": 10, "total_pages": 1 }
}

Retail Sales Index

The rsi metric contains all 366 monthly observations published by ONS from 1996 JAN to 2026 JUN. CDID J5EK is the headline volume index: seasonally adjusted, all retailing including automotive fuel, with the current ONS base year equal to 100. Use it to track changes in the quantity bought by consumers; it is an index level, not monthly percentage growth.

Captured from /v1/economics/indicators/rsi?per_page=2 on the reset development API after the 10 August 2026 ONS import:

{"data":{"dataset_id":"rsi","dataset_name":"Retail Sales Index (volume, seasonally adjusted, all retailing including fuel)","unit":"index","observations":[{"time_period":"2026 JUN","date":"2026-06-01","value":104.8,"geography":"K02000001"},{"time_period":"2026 MAY","date":"2026-05-01","value":103.8,"geography":"K02000001"}]},"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"ONS","source_url":"https://www.ons.gov.uk"},"pagination":{"total":366,"page":1,"per_page":2,"total_pages":183}}

Vacancies by industry (VACS02)

vacancies is ONS CDID AP2Y: UK vacancies in thousands, seasonally adjusted, published monthly as centred three-month averages. The API also exposes all 18 VACS02 SIC 2007 industry sections as vacancies_b through vacancies_s. Each series contains the full 301 observations from 2001 MAY to 2026 MAY. Source: AP2Y metadata and time series and the published VACS02 table, OGL v3.0.

Captured from /v1/economics/indicators/vacancies?per_page=2 on the reset development API after the 10 August 2026 ONS import:

{"data":{"dataset_id":"vacancies","dataset_name":"UK Vacancies (three-month average, seasonally adjusted)","unit":"thousands","observations":[{"time_period":"2026 MAY","date":"2026-05-01","value":712.0,"geography":"K02000001"},{"time_period":"2026 APR","date":"2026-04-01","value":710.0,"geography":"K02000001"}]},"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"ONS","source_url":"https://www.ons.gov.uk"},"pagination":{"total":301,"page":1,"per_page":2,"total_pages":151}}

Parameters

Parameter	Type	Required	Description
`metric`	string (path)	Yes	`gdp`, `unemployment`, `hpi`, `rsi`, `vacancies`, or `vacancies_b`–`vacancies_s` (SIC sections)
`from`	string (query)	No	Start date in `YYYY-MM-DD` format
`to`	string (query)	No	End date in `YYYY-MM-DD` format

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.govdata.dev/v1/economics/indicators/unemployment?from=2024-01&to=2024-12"

Response

{
  "data": {
    "dataset_id": "unemployment",
    "dataset_name": "Unemployment Rate",
    "unit": "percent",
    "observations": [
      { "time_period": "2024 JAN", "date": "2024-01-01", "value": 4.0, "geography": "K02000001" },
      { "time_period": "2024 FEB", "date": "2024-02-01", "value": 4.1, "geography": "K02000001" }
    ]
  },
  "meta": {
    "api_version": "v1",
    "licence": "Open Government Licence v3.0",
    "source": "Office for National Statistics",
    "source_url": "https://www.ons.gov.uk"
  }
}

Error responses and data notes

{"error":{"code":"invalid_parameter","message":"Invalid date format. Use YYYY-MM-DD.","documentation_url":"https://docs.govdata.dev/errors/invalid_parameter"}}

Unknown metrics or malformed dates return 400; a valid filter with no observations returns an empty 200 response. Each series follows its ONS release timetable and may be revised. Units and coverage differ by metric; use the returned dataset name and unit, and retain ONS/OGL v3.0 attribution.

Latest Indicator

GET /v1/economics/indicators/:metric/latest

metric * — Economic indicator

response

Waiting for request...

Returns the most recent published observation for the given economic indicator.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.govdata.dev/v1/economics/indicators/unemployment/latest

Response

{"data":{"dataset_id":"vacancies","dataset_name":"UK Vacancies (three-month average, seasonally adjusted)","unit":"thousands","time_period":"2026 MAY","date":"2026-05-01","value":712.0,"geography":"K02000001"},"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"ONS","source_url":"https://www.ons.gov.uk"}}

The value is verified against economics_data_points.yml. Vacancies are a centred three-month average in thousands, not a count for May alone.

Error responses and data notes

{"error":{"code":"not_found","message":"No data available for vacancies.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Unknown metrics return 400 and a valid metric without data returns 404. The endpoint inherits each indicator's ONS cadence, data-derived coverage, units, OGL v3.0 attribution, and revision caveats.

Population Estimates

Returns ONS mid-year all-ages population estimates for the UK, countries, English regions and UK local authorities. Use it for market sizing, service planning, per-capita analysis and area profiles.

GET /v1/economics/population

Parameters

Name	Type	Required	Default	Description
`geography_code`	string	No	—	Exact ONS geography code
`geography_name`	string	No	—	Literal case-insensitive geography-name prefix; % and _ are not wildcards
`from_year`	integer	No	—	Inclusive first reference year
`to_year`	integer	No	—	Inclusive last reference year
`sex`	string	No	—	all, female or male
`page`	integer	No	1	Page number
`per_page`	integer	No	25	Rows per page, maximum 100

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.govdata.dev/v1/economics/population?geography_code=E09000001&from_year=2023&sex=all"

Response

{"data":[{"geography_code":"E09000001","geography_name":"City of London","geography_type":"local_authority","year":2023,"sex":"all","population":10847,"median_age":null}],"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"Office for National Statistics","source_url":"https://www.ons.gov.uk/peoplepopulationandcommunity/populationandmigration/populationestimates/datasets/populationestimatesforukenglandandwalesscotlandandnorthernireland"},"pagination":{"total":1,"page":1,"per_page":25,"total_pages":1}}

population is a count of usual residents at 30 June. median_age is reserved but null in this slice.

GET /v1/economics/population/:geography_code

Returns all loaded estimates for one exact official geography code, newest first. Use this after selecting an area from the collection endpoint.

GET /v1/economics/population/:geography_code

Parameters

Name	Type	Required	Default	Description
`geography_code`	string (path)	Yes	—	Exact ONS geography code, matched case-insensitively.

curl -H "Authorization: Bearer YOUR_API_KEY" "https://api.govdata.dev/v1/economics/population/E09000001"

Response

{"data":[{"geography_code":"E09000001","geography_name":"City of London","geography_type":"local_authority","year":2023,"sex":"all","population":10847,"median_age":null}],"meta":{"api_version":"v1","licence":"Open Government Licence v3.0","source":"Office for National Statistics","source_url":"https://www.ons.gov.uk/peoplepopulationandcommunity/populationandmigration/populationestimates/datasets/populationestimatesforukenglandandwalesscotlandandnorthernireland"}}

The value is from the population controller fixture; the development population table is currently empty.

Coverage, annual cadence, OGL v3.0 attribution, revision, and boundary caveats are the same as the collection endpoint.

Error responses

404 Not Found — no estimates exist for the geography code.

{"error":{"code":"not_found","message":"No population estimates found for NOPE.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Errors

The collection has no required filters, so 400 and 422 are not applicable. The show route returns 404 for an unknown geography code:

{"error":{"code":"not_found","message":"No population estimates found for NOPE.","documentation_url":"https://docs.govdata.dev/errors/not_found"}}

Data notes

Coverage is mid-2011 to mid-2024 for UK countries and local authorities, plus English regions through mid-2023, split by female, male and all. Updated annually after the usual summer ONS release and licensed under OGL v3.0. Values can be revised and boundary changes affect comparisons. Single-year ages and median age are deferred; this endpoint contains all-ages summaries only.

Economic data is sourced from the Office for National Statistics and updated weekly. Contains public sector information licensed under the Open Government Licence v3.0.

Data Coverage

Source	Office for National Statistics (ONS)
Date range	CPI 1989–, CPIH 1989–, RPI 1948–, unemployment 1971–, HPI 1989–, RSI 1996 JAN–2026 JUN, vacancies 2001 MAY–2026 MAY
Records	9,319 data points across 26 metrics, including 5,719 headline and industry vacancy observations
Updated	Weekly (Monday)
Limitations	Most series publish with a 1–2 month lag. RSI values are revised by ONS and the index base year changes periodically, so compare values from the same current vintage.