Package 'hmrc'

Title: Download and Tidy 'HMRC' Statistical Data
Description: Provides functions to download, parse, and tidy statistical data published by 'HM Revenue and Customs' ('HMRC') on 'GOV.UK'. Returns annotated 'hmrc_tbl' data frames with provenance metadata (source URL, publication date, fetch time, cell methods) for reproducible fiscal research. Covers monthly tax receipts (42 series), 'VAT' (from 1973), fuel duties (from 1990), tobacco duties (from 1991), 'Corporation Tax' receipts, stamp duty, research and development tax credits (from 2000), tax gap estimates (from 2005), 'Income Tax' liabilities by income range, Capital Gains Tax, Inheritance Tax, the Patent Box, creative industries reliefs, and monthly property transaction counts. File URLs are resolved at runtime via the 'GOV.UK' Content API <https://www.gov.uk/api/content>, so data is always current without hardcoded URLs. Files are cached locally between sessions.
Authors: Charles Coverdale [aut, cre]
Maintainer: Charles Coverdale <[email protected]>
License: MIT + file LICENSE
Version: 0.4.1
Built: 2026-10-13 13:21:48 UTC
Source: https://github.com/charlescoverdale/hmrc

Help Index

HMRC dataset catalogue

Description

A data frame describing every HMRC dataset known to the package, including those exposed by an ⁠hmrc_*⁠ function and those on the development roadmap (where function_name is NA). Use hmrc_search() for keyword search and hmrc_publications() for a tidy index.

Usage

catalogue

Format

A data frame with columns:

dataset

Character. Short identifier.

publication

Character. GOV.UK publication name.

function_name

Character. Exporting function (or NA).

frequency

Character. monthly, quarterly, annual, etc.

start

Character. First period of the published series.

publisher

Character. Usually "HMRC".

slug

Character. GOV.UK statistics slug.

url

Character. URL of the publication landing page.

description

Character. One-line description.

tags

Character. Space-separated keywords searched by hmrc_search().

Inspect the local HMRC cache

Description

Returns a tidy table of files currently held in the package cache, with size and age. Useful for understanding what is stored locally and deciding when to clear stale files via hmrc_clear_cache().

Usage

hmrc_cache_info()

Value

A data frame with columns file, extension, size_bytes, size_mb, modified (POSIXct), age_days, path. The data frame is empty (zero rows) if the cache directory does not exist or is empty. The cache directory itself is attached as the attribute "cache_dir".

See Also

Other infrastructure: hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
info <- hmrc_cache_info()
attr(info, "cache_dir")
options(op)

Download HMRC Capital Gains Tax statistics

Description

Downloads and tidies HMRC Table 1 of the Capital Gains Tax statistics bulletin: estimated number of CGT taxpayers, amounts of gains, and tax liabilities by year of disposal. Data runs from 1987-88 onwards and is published annually each summer.

Usage

hmrc_capital_gains(tax_year = NULL, measure = NULL, cache = TRUE)

Arguments

tax_year

Character vector or NULL (default = all years). Filter to specific tax years, e.g. "2022-23".
measure

Character vector or NULL (default = all measures). Valid values: "taxpayers_total_thousands", "taxpayers_individuals_thousands", "taxpayers_trusts_thousands", "males_pct", "females_pct", "gains_individuals_gbp_m", "gains_trusts_gbp_m", "gains_total_gbp_m", "tax_individuals_gbp_m", "tax_trusts_gbp_m", "tax_total_gbp_m".
cache

Logical. Use cached file if available (default TRUE).

Details

Gains are after the deduction of taper relief and losses plus attributed gains, but before deduction of the Annual Exempt Amount. Trusts include personal representatives of the deceased. Statistics for the latest tax years are provisional and are revised in subsequent publications as late returns arrive.

Value

An hmrc_tbl (long format) with columns tax_year, measure, value, and status ("provisional" for the years HMRC marks as provisional, otherwise NA). Numbers of taxpayers are in thousands; amounts in millions of pounds; percentages in per cent. Suppressed cells return NA.

Source

https://www.gov.uk/government/statistics/capital-gains-tax-statistics

See Also

Other data fetchers: hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  cgt <- hmrc_capital_gains(measure = "tax_total_gbp_m")
  tail(cgt)
})
options(op)

Clear the local HMRC data cache

Description

Deletes locally cached data files downloaded by the package. By default all cached files are removed; pass max_age_days to remove only files older than that.

Usage

hmrc_clear_cache(max_age_days = NULL)

Arguments

max_age_days

Numeric or NULL. If NULL (default), every cached file is removed. If a number, only files modified more than that many days ago are removed.

Value

Invisibly returns the number of files deleted.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
hmrc_clear_cache(max_age_days = 30)
hmrc_clear_cache()
options(op)

Download HMRC Corporation Tax receipts by type

Description

Downloads and tidies the HMRC Corporation Tax Statistics annual publication, reporting receipts broken down by tax type for the most recent six financial years. Published annually in September.

Usage

hmrc_corporation_tax(cache = TRUE)

Arguments

cache

Logical. Use cached file if available (default TRUE).

Details

Some levies (e.g. Residential Property Developer Tax, Electricity Generators Levy) were introduced mid-series and have NA values for earlier years.

Value

An hmrc_tbl with columns tax_year, type, description, receipts_gbp_m.

Source

https://www.gov.uk/government/collections/analyses-of-corporation-tax-receipts-and-liabilities

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  ct <- hmrc_corporation_tax()
  ct[ct$type == "all_corporate_taxes", ]
})
options(op)

Download HMRC Creative Industries tax relief statistics

Description

Downloads and tidies Table 1 (annual time series) of the HMRC Creative Industries Statistics for each of the eight creative-industries reliefs: Film, High-end TV, Animation, Children's TV, Video Games, Theatre, Orchestra, and Museums and Galleries Exhibition. Published annually each August.

Usage

hmrc_creative_industries(sector = NULL, tax_year = NULL, cache = TRUE)

Arguments

sector

Character vector or NULL (default = all sectors). Valid values: "film", "high_end_tv", "animation", "childrens_tv", "video_games", "theatre", "orchestra", "museum". Any relief HMRC adds to the release later (for example the Audio-Visual and Video Games Expenditure Credits) is included when sector = NULL, keyed by a snake_case version of its sheet name.
tax_year

Character vector or NULL (default = all years).
cache

Logical. Use cached file if available (default TRUE).

Details

Creative Industries reliefs are paid on an accruals basis. The latest tax year in each sector's table is provisional and uplifted by HMRC for claims not yet received; status is recorded in the status column. Sector tables differ slightly in their column set (films track productions, video games track productions, theatre tracks claims/productions, museums track exhibitions, etc.); columns absent from a sector's table are returned as NA.

Value

An hmrc_tbl with columns:

sector

Character. Creative-industries sector identifier.

tax_year

Character. Tax year, e.g. "2023-24".

companies

Numeric. Number of companies (where reported).

claims

Numeric. Number of claims (where reported).

productions

Numeric. Number of productions (films, programmes, games, exhibitions, etc., where reported).

relief_gbp_m

Numeric. Amount of relief paid, GBP million.

status

Character. HMRC revision status (e.g. "Unchanged", "Provisional").

Source

https://www.gov.uk/government/collections/creative-industries-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  film <- hmrc_creative_industries(sector = "film")
  tail(film)
})
options(op)

Download HMRC hydrocarbon oil (fuel duty) receipts

Description

Downloads and tidies the HMRC Hydrocarbon Oils Bulletin, which reports monthly fuel duty receipts. Data runs from January 1990 to the most recent published month, updated twice per year (January and July).

Usage

hmrc_fuel_duties(fuel = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

fuel

Character vector or NULL (default = all). Valid values: "total", "petrol", "diesel", "other".
start

Character "YYYY-MM" or a Date object.
end

Character "YYYY-MM" or a Date object.
cache

Logical. Use cached file if available (default TRUE).

Details

petrol and diesel are HMRC's "Total petrol" and "Total diesel" columns. other is the sum of fuel oil, gas oil and road fuel gases. total is HMRC's total hydrocarbon oils receipts.

Value

An hmrc_tbl with columns date, fuel, description, receipts_gbp_m, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/hydrocarbon-oils-bulletin

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  fuel <- hmrc_fuel_duties(fuel = "total", start = "2024-01")
  head(fuel)
})
options(op)

Download HMRC Income Tax liabilities by income range

Description

Downloads and tidies HMRC Table 2.5, which reports the number of Income Tax payers and their liabilities grouped by total income range, for each available tax year. Numbers of taxpayers are in thousands; amounts are in millions of pounds unless otherwise noted. Published annually in May/June.

Usage

hmrc_income_tax_stats(tax_year = NULL, cache = TRUE)

Arguments

tax_year

Character vector or NULL (default = all years). Filter to specific tax years, e.g. "2023-24".
cache

Logical. Use cached file if available (default TRUE).

Details

The earliest tax year is outturn from the Survey of Personal Incomes; later years are HMRC projections from that survey. The estimate column marks which is which. Values suppressed for small sample sizes are returned as NA.

Value

An hmrc_tbl with columns tax_year, income_range, income_lower_gbp, taxpayers_thousands, total_income_gbp_m, tax_liability_gbp_m, average_rate_pct (in per cent), average_tax_gbp, and estimate ("outturn" or "projection").

Source

https://www.gov.uk/government/statistics/income-tax-liabilities-by-income-range

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  it <- hmrc_income_tax_stats()
  it[it$income_range == "All Ranges", ]
})
options(op)

Download HMRC Inheritance Tax liabilities by estate band

Description

Downloads and tidies HMRC Table 12.1a of the Inheritance Tax Liabilities Statistics: numbers of estates, tax due, average tax, and average effective tax rate, broken down by net-estate band, for the latest published year of death. Published annually in July, about two years after the end of the year of death because estates take time to settle.

Usage

hmrc_inheritance_tax(cache = TRUE)

Arguments

cache

Logical. Use cached file if available (default TRUE).

Value

An hmrc_tbl (long format) with columns:

tax_year

Character. Year of death, e.g. "2022-23".

estate_band_lower_gbp

Numeric. Lower limit of the net-estate band in pounds.

estate_band

Character. Plain-English label, e.g. "GBP 0-100k", "Total".

measure

Character. One of "number_not_taxed", "number_taxed", "tax_due_gbp_m", "avg_tax_gbp", "effective_rate_pct" (in per cent).

value

Numeric. Value, with ⁠[z]⁠ (no tax due to NRB) and ⁠[c]⁠ (disclosure suppression) returned as NA.

Source

https://www.gov.uk/government/statistics/inheritance-tax-liabilities-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  iht <- hmrc_inheritance_tax()
  iht[iht$estate_band == "Total", ]
})
options(op)

List available tax heads in the HMRC Tax Receipts bulletin

Description

Returns a data frame describing all tax and duty heads available in hmrc_tax_receipts(). No network connection is required: the data is bundled with the package.

Usage

hmrc_list_tax_heads()

Value

A data frame with columns:

tax_head

Character. Identifier used in the tax argument of hmrc_tax_receipts().

description

Character. Plain-English description.

category

Character. Broad grouping.

available_from

Character. First year with receipts in HMRC's monthly table at the package release (NA if none in the current window).

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_meta(), hmrc_publications(), hmrc_search()

Examples

hmrc_list_tax_heads()

Provenance metadata of an hmrc_tbl

Description

Returns the provenance list attached to a result from any ⁠hmrc_*⁠ data fetcher: source URL, attachment URL, the GOV.UK publication timestamp of the edition (published_at), fetch time, vintage, cell methods, and so on. Useful for citation, audit trails, and reproducibility.

Usage

hmrc_meta(x)

Arguments

x

An object returned by an ⁠hmrc_*⁠ data function.

Value

A named list, or NULL if x has no metadata.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_publications(), hmrc_search()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tr <- hmrc_tax_receipts(tax = "vat", start = "2024-01")
  hmrc_meta(tr)
})
options(op)

Download HMRC Patent Box relief statistics

Description

Downloads and tidies Table 1 of the HMRC Patent Box Relief Statistics: annual number of companies electing into the Patent Box regime and the total relief claimed (in GBP million). The Patent Box was introduced from 1 April 2013; data runs from tax year 2013-14 to the most recent published year (typically with a one-year provisional lag). Published annually each September.

Usage

hmrc_patent_box(tax_year = NULL, cache = TRUE)

Arguments

tax_year

Character vector or NULL (default = all years). Filter to specific tax years, e.g. "2023-24".
cache

Logical. Use cached file if available (default TRUE).

Value

An hmrc_tbl with columns:

tax_year

Character. Tax year, e.g. "2023-24".

companies

Numeric. Number of companies electing into the regime (rounded to nearest 5 by HMRC).

relief_gbp_m

Numeric. Total relief in millions of pounds.

status

Character. HMRC's label for the year where it gives one (e.g. "projection" for the latest year), otherwise NA.

Source

https://www.gov.uk/government/statistics/patent-box-reliefs-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  hmrc_patent_box()
})
options(op)

Download monthly UK property transaction counts

Description

Downloads and tidies the HMRC Monthly Property Transactions bulletin, which counts residential and non-residential property transactions (SDLT returns, LBTT in Scotland, LTT in Wales) for England, Scotland, Wales, Northern Ireland, and the UK total. Data runs from April 2005 to the most recent completed month.

Usage

hmrc_property_transactions(
  type = c("all", "residential", "non_residential"),
  nation = NULL,
  start = NULL,
  end = NULL,
  cache = TRUE
)

Arguments

type

Character. One of "all" (default), "residential", or "non_residential".
nation

Character vector or NULL (default = all nations). Valid values: "uk", "england", "scotland", "wales", "northern_ireland".
start

Character "YYYY-MM" or a Date object.
end

Character "YYYY-MM" or a Date object.
cache

Logical. Use cached file if available (default TRUE).

Value

An hmrc_tbl with columns date, nation, type, transactions, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/monthly-property-transactions-completed-in-the-uk-with-value-40000-or-above

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  mpt <- hmrc_property_transactions(type = "residential", nation = "england",
                                    start = "2025-01")
  head(mpt)
})
options(op)

Index of HMRC publications known to the package

Description

Tidy roster of HMRC publications, marking which are exposed via an ⁠hmrc_*⁠ function and which are on the development roadmap. Useful for planning analyses, citing the package, and tracking coverage over time.

Usage

hmrc_publications(status = c("all", "implemented", "planned"))

Arguments

status

One of "all" (default), "implemented", or "planned".

Value

A data frame with one row per publication and a status column ("implemented" or "planned").

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_search()

Examples

# Everything in the catalogue
hmrc_publications()

# Only roadmap items
hmrc_publications("planned")

Download HMRC R&D tax credit statistics

Description

Downloads and tidies the HMRC Research and Development Tax Credits Statistics publication, covering the SME R&D Relief and Research and Development Expenditure Credit (RDEC) schemes. Annual data runs from 2000-01 to the most recent financial year, published annually in September.

Usage

hmrc_rd_credits(scheme = NULL, measure = NULL, cache = TRUE)

Arguments

scheme

Character vector or NULL (default = all schemes). Valid values: "sme", "rdec", "total".
measure

Character vector or NULL (default = all measures). Valid values: "claims", "amount_gbp_m".
cache

Logical. Use cached file if available (default TRUE).

Details

Data before 2003-04 covers only the SME scheme (RDEC was introduced in 2002). Figures for the most recent years are provisional and subject to revision as late claims are processed; the status column carries HMRC's label. rdec is HMRC's "LC & RDEC Total" column and total is HMRC's all-schemes total.

Value

An hmrc_tbl with columns tax_year, scheme, description, measure, value, and status (HMRC's revision label, e.g. "Unchanged", "Provisional, Revised", "Provisional, Uplifted").

Source

https://www.gov.uk/government/statistics/corporate-tax-research-and-development-tax-credit

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  rd <- hmrc_rd_credits(measure = "amount_gbp_m")
  tail(rd)
})
options(op)

Search the HMRC dataset catalogue

Description

Fuzzy keyword search across publication name, description, tags, and dataset identifier. Returns a tidy table of matching rows so users can discover what the package exposes (and what is on the roadmap).

Usage

hmrc_search(query = NULL, implemented = NULL, frequency = NULL)

Arguments

query

Character. Keyword or regex pattern. Case-insensitive. Matches anywhere in dataset, publication, description, or tags. If NULL or empty, the full catalogue is returned.
implemented

Logical or NULL. If TRUE, only rows with a working function_name are returned. If FALSE, only roadmap rows. NULL (default) returns both.
frequency

Optional character vector to filter by frequency (e.g. "monthly", "annual").

Value

A data frame, sorted with implemented datasets first.

See Also

Other infrastructure: hmrc_cache_info(), hmrc_clear_cache(), hmrc_list_tax_heads(), hmrc_meta(), hmrc_publications()

Examples

# Everything mentioning VAT
hmrc_search("vat")

# Only annual publications already implemented
hmrc_search(implemented = TRUE, frequency = "annual")

# Roadmap items mentioning capital gains
hmrc_search("capital gains", implemented = FALSE)

Download HMRC stamp duty receipts

Description

Downloads and tidies the HMRC Annual Stamp Tax Statistics, covering Stamp Duty Land Tax (SDLT), Stamp Duty Reserve Tax (SDRT) on shares, and other stamp duties. Annual data from 2003-04 to the most recent financial year, published each December.

Usage

hmrc_stamp_duty(type = NULL, cache = TRUE)

Arguments

type

Character vector or NULL (default = all types). Valid values: "sdlt_property", "sdlt_leases", "sdlt_total", "sdrt", "stamp_duty", "shares_total", "total".
cache

Logical. Use cached file if available (default TRUE).

Details

sdlt_total is SDLT on all property; shares_total is Stamp Duty Reserve Tax plus Stamp Duty on share documents; total is all stamp taxes. Land transaction taxes were devolved to Scotland (LBTT) in April 2015 and Wales (LTT) in April 2018, so SDLT after those dates covers England and Northern Ireland only.

Value

An hmrc_tbl with columns tax_year, type, description, receipts_gbp_m (rounded to nearest GBP 5m by HMRC).

Source

https://www.gov.uk/government/statistics/uk-stamp-tax-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  sd <- hmrc_stamp_duty(type = c("sdlt_total", "total"))
  tail(sd)
})
options(op)

Download HMRC tax gap estimates

Description

Downloads and tidies the HMRC Measuring Tax Gaps tables: estimates of the difference between the tax that should in theory be paid and the tax actually collected, by tax, taxpayer type and component. Since the 2026 edition HMRC publishes a consistent time series from 2005-06, and every edition revises earlier years. Published annually in June.

Usage

hmrc_tax_gap(tax = NULL, tax_year = NULL, cache = TRUE)

Arguments

tax

Character vector or NULL (default = all taxes). Filter on the tax column: "VAT", "Excise duty", "Income Tax, NICs, Capital Gains Tax", "Corporation Tax", "Other taxes", "Total tax gap".
tax_year

Character vector, "latest", or NULL (default = all years). Filter to specific tax years, e.g. "2024-25".
cache

Logical. Use cached file if available (default TRUE).

Details

Rows that appear only in the GBP table (avoidance and hidden economy components) have gap_pct of NA. Estimates HMRC shows as ⁠<0.1⁠ (below GBP 0.05bn) are returned as NA. Each June edition revises the whole series, so results change between editions; hmrc_meta() records the edition's publication date.

Value

An hmrc_tbl with columns:

tax_year

Character. Tax year, e.g. "2024-25".

tax

Character. Tax group, e.g. "VAT", "Corporation Tax".

type

Character. Sub-group, e.g. "Self Assessment", "Tobacco duty", or the group total.

component

Character. Taxpayer group or duty, e.g. "Small businesses", "Cigarette duty".

gap_pct

Numeric. Tax gap as a per cent of theoretical liabilities (Table 1.1).

gap_gbp_bn

Numeric. Tax gap in GBP billion (Table 1.2).

Source

https://www.gov.uk/government/statistics/measuring-tax-gaps

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_receipts(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  gap <- hmrc_tax_gap(tax = "Total tax gap")
  tail(gap)
})
options(op)

Download HMRC tax receipts and National Insurance contributions

Description

Downloads and tidies the monthly HMRC Tax Receipts and National Insurance Contributions bulletin published on GOV.UK. The bulletin covers all major UK taxes and duties at monthly frequency and is updated on approximately the 15th working day of each month. HMRC's monthly table is a rolling window: it currently starts in April 2017.

Usage

hmrc_tax_receipts(tax = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

tax

Character vector of tax head identifiers, or NULL (default) to return all available series. Use hmrc_list_tax_heads() to see valid values and descriptions.
start

Character "YYYY-MM" or a Date object. If provided, rows before this month are dropped.
end

Character "YYYY-MM" or a Date object. If provided, rows after this month are dropped.
cache

Logical. If TRUE (default), the downloaded file is cached locally and reused on subsequent calls. Use hmrc_clear_cache() to reset.

Details

Months with no receipts for a head (for example Bank Levy outside its instalment months) are marked ⁠[X]⁠ by HMRC and returned as NA. If HMRC adds a new series to the bulletin (Vaping Products Duty is due from October 2026), it is returned under a snake_case tax_head built from its column label, with a one-off message, until the package adds it to hmrc_list_tax_heads().

Value

An hmrc_tbl (subclass of data.frame) with columns:

date

Date. The first day of the reference month.

tax_head

Character. Tax or duty identifier (see hmrc_list_tax_heads()).

description

Character. Plain-English series label.

receipts_gbp_m

Numeric. Cash receipts in millions of pounds (GBP).

Provenance metadata (source URL, fetch time, vintage) is attached as the "hmrc_meta" attribute and can be inspected with hmrc_meta().

Source

https://www.gov.uk/government/statistics/hmrc-tax-and-nics-receipts-for-the-uk

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tobacco_duties(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tr <- hmrc_tax_receipts(tax = c("income_tax", "vat"), start = "2025-04")
  head(tr)
})
options(op)

Download HMRC tobacco duty receipts

Description

Downloads and tidies the HMRC Tobacco Bulletin, which reports monthly tobacco products duty receipts by product type. Data runs from January 1991 to the most recent published month.

Usage

hmrc_tobacco_duties(product = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

product

Character vector or NULL (default = all products). Valid values: "cigarettes", "cigars", "hand_rolling", "other", "total".
start

Character "YYYY-MM" or a Date object.
end

Character "YYYY-MM" or a Date object.
cache

Logical. Use cached file if available (default TRUE).

Value

An hmrc_tbl with columns date, product, description, receipts_gbp_m, and provisional (logical, TRUE for months HMRC flags as provisional).

Source

https://www.gov.uk/government/statistics/tobacco-bulletin

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_vat()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  tob <- hmrc_tobacco_duties(product = "cigarettes", start = "2024-01")
  head(tob)
})
options(op)

Download HMRC VAT receipts

Description

Downloads and tidies the HMRC VAT Annual Statistics bulletin, which reports monthly VAT receipts broken down into payments, repayments, import VAT, and home VAT. Monthly data runs from April 1973; the bulletin is published annually (December).

Usage

hmrc_vat(measure = NULL, start = NULL, end = NULL, cache = TRUE)

Arguments

measure

Character vector or NULL (default = all measures). Valid values: "total", "payments", "repayments", "import_vat", "home_vat".
start

Character "YYYY-MM" or a Date object.
end

Character "YYYY-MM" or a Date object.
cache

Logical. Use cached file if available (default TRUE).

Details

Note that early years (pre-1985) have suppressed payment and repayment splits; only the total is available for those periods. From January 2021, import VAT collected via postponed VAT accounting is recorded within payments and repayments rather than the import VAT column.

Value

An hmrc_tbl with columns date, measure, description, receipts_gbp_m. Repayments are negative.

Source

https://www.gov.uk/government/statistics/value-added-tax-vat-annual-statistics

See Also

Other data fetchers: hmrc_capital_gains(), hmrc_corporation_tax(), hmrc_creative_industries(), hmrc_fuel_duties(), hmrc_income_tax_stats(), hmrc_inheritance_tax(), hmrc_patent_box(), hmrc_property_transactions(), hmrc_rd_credits(), hmrc_stamp_duty(), hmrc_tax_gap(), hmrc_tax_receipts(), hmrc_tobacco_duties()

Examples

op <- options(hmrc.cache_dir = file.path(tempdir(), "hmrc"))
try({
  vat <- hmrc_vat(measure = c("total", "repayments"), start = "2024-01")
  head(vat)
})
options(op)

Tax head lookup table

Description

A data frame describing all tax and duty series available in hmrc_tax_receipts().

Usage

tax_heads

Format

A data frame with 42 rows and 4 columns:

tax_head

Character. Identifier used in the tax argument of hmrc_tax_receipts().

description

Character. Plain-English description.

category

Character. Broad grouping: "income", "nics", "consumption", "property", "environment", "other", or "total".

available_from

Character. First year with receipts in HMRC's monthly table at the package release. The table is a rolling window (currently April 2017 onwards), so long-standing taxes show the window start. NA means no receipts in the current window.

Source

Derived from the HMRC Tax Receipts and NICs bulletin. https://www.gov.uk/government/statistics/hmrc-tax-and-nics-receipts-for-the-uk