Package {carbondata}

carbondata: Access Carbon Market Data from Emissions Trading Systems and Voluntary Registries

Description

Unified access to carbon market data from compliance emissions trading systems ('EU ETS', 'UK ETS', 'RGGI', California Cap-and-Trade) and voluntary carbon markets (Verra, Gold Standard, American Carbon Registry, Climate Action Reserve, via the Berkeley Voluntary Registry Offsets Database and the 'CarbonPlan' 'OffsetsDB' API). Includes cross-market price data from the 'International Carbon Action Partnership' ('ICAP') Allowance Price Explorer https://icapcarbonaction.com/en/ets-prices, global carbon pricing from the World Bank Carbon Pricing Dashboard https://carbonpricingdashboard.worldbank.org/, and the historical 'RFF' World Carbon Pricing Database following Dolphin, Pollitt and Newbery (2020) doi:10.1038/s41597-022-01659-x. Data is downloaded from public sources on first use and cached locally.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://charlescoverdale.github.io/carbondata/

• https://github.com/charlescoverdale/carbondata

• Report bugs at https://github.com/charlescoverdale/carbondata/issues

Inspect the local carbondata cache

Description

Returns information about the local cache: directory, file count, size, and list of cached files. Useful for debugging stale results or deciding whether to call co2_clear_cache().

Usage

co2_cache_info()

Value

A list with elements dir, n_files, size_bytes, size_human, and files (a data frame with name, size_bytes, modified).

See Also

Other configuration: co2_clear_cache()

Examples

op <- options(carbondata.cache_dir = tempdir())
co2_cache_info()
options(op)

Climate Action Data Trust (not supported)

Description

CAD Trust is the Chia-Network "cadt" software designed to be self-hosted. There is no unauthenticated public API. To use CAD Trust data you must either:

• Self-host a cadt node, or

• Arrange a private partnership for API access via https://climateactiondata.org/how-to-connect/

Usage

co2_cad_trust(...)

Arguments

Details

This function is a placeholder that errors with guidance. It will gain an implementation once CAD Trust offers a stable public endpoint.

Value

Never returns (always errors).

See Also

Other voluntary markets: co2_offsets_db(), co2_vrod()

Examples

## Not run: 
co2_cad_trust()

## End(Not run)

California overall emissions caps

Description

Fetches the California Cap-and-Trade program overall cap and allocation channels, by vintage year.

Usage

co2_california_caps(refresh = FALSE)

Arguments

Value

A data frame.

See Also

Other compliance markets: co2_california_prices(), co2_rggi_allowances(), co2_rggi_state_proceeds(), co2_ukets(), co2_ukets_allocations()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  caps <- co2_california_caps()
})
options(op)

California Cap-and-Trade auction settlement prices

Description

Fetches the California Air Resources Board auction settlement price time series, updated quarterly after each joint California- Quebec auction.

Usage

co2_california_prices(refresh = FALSE)

Arguments

Value

A data frame with joint_auction, quarter, settlement_price_usd, reserve_price_usd.

See Also

Other compliance markets: co2_california_caps(), co2_rggi_allowances(), co2_rggi_state_proceeds(), co2_ukets(), co2_ukets_allocations()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  prices <- co2_california_prices()
})
options(op)

Clear the carbondata cache

Description

Deletes all locally cached carbon market data files. The next call to any data function will re-download.

Usage

co2_clear_cache()

Value

Invisibly returns NULL.

See Also

Other configuration: co2_cache_info()

Examples

op <- options(carbondata.cache_dir = tempdir())
co2_clear_cache()
options(op)

Emissions-weighted carbon prices (ECP)

Description

Fetches the emissions-weighted carbon price dataset published alongside the World Carbon Pricing Database at https://worldcarbonpricing.org. Unlike the raw WCPD files, these endpoints remain open and are updated with each release, so this is the current route to World Carbon Pricing Database derived data.

Usage

co2_ecp_prices(
  level = c("jurisdiction", "sector", "coverage", "coverage_sector", "region"),
  gas = "CO2",
  country = NULL,
  refresh = FALSE
)

Arguments

Details

level = "jurisdiction" returns average effective carbon prices by jurisdiction and year and "sector" disaggregates by IPCC sector. Coverage shares, the fraction of emissions subject to a price, come from "coverage" (by jurisdiction) and "coverage_sector".

"region" is accepted because the publisher documents the endpoint, but their server currently has no data file behind it for any gas; the call errors with that explanation until they restore it.

Value

A data frame.

References

Dolphin, G., Xiahou, Q. (2022). "World carbon pricing database: sources and methods." Scientific Data, 9, 573. https://doi.org/10.1038/s41597-022-01659-x

See Also

Other aggregators: co2_icap_prices(), co2_icap_systems(), co2_rff_pricing(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  ecp <- co2_ecp_prices(country = "United Kingdom")
})
options(op)

EU ETS free allowance allocations

Description

Returns free allowance allocations per installation per year. Same source file as co2_euets_emissions().

Usage

co2_euets_allocations(
  country = NULL,
  year = NULL,
  file_year = NULL,
  scheme = c("ets1", "ets2", "all"),
  refresh = FALSE
)

Arguments

Value

A data frame with country, installation_id, installation_name, activity, scheme, year, allocation_eua.

See Also

Other EU ETS: co2_euets_emissions(), co2_euets_files(), co2_euets_installations(), co2_euets_price(), co2_euets_surrendered()

Examples

op <- options(carbondata.cache_dir = tempdir())
alloc <- co2_euets_allocations(country = "DE")
options(op)

EU ETS verified emissions

Description

Fetches annual verified greenhouse-gas emissions for installations covered by the EU Emissions Trading System, from the DG CLIMA Union Registry bulk download. Coverage: ~10,000 stationary installations plus ~1,500 aircraft operators across the EU, EEA, and linked Swiss ETS. Emissions data from 2005 onwards; annual files published each April for the prior compliance year.

Usage

co2_euets_emissions(
  country = NULL,
  year = NULL,
  file_year = NULL,
  scheme = c("ets1", "ets2", "all"),
  refresh = FALSE
)

Arguments

Value

A data frame with columns country, installation_id, installation_name, activity, scheme, year, verified_emissions_tco2e, allocation_eua.

See Also

Other EU ETS: co2_euets_allocations(), co2_euets_files(), co2_euets_installations(), co2_euets_price(), co2_euets_surrendered()

Examples

op <- options(carbondata.cache_dir = tempdir())
de <- co2_euets_emissions(country = "DE")
options(op)

List the EU ETS data file vintages available

Description

Returns a data frame of the DG CLIMA file vintages available. The package scrapes the Union Registry page at runtime so new annual releases appear automatically; when the page is unreachable, the vintages bundled with the package are listed instead.

Usage

co2_euets_files()

Value

A data frame.

See Also

Other EU ETS: co2_euets_allocations(), co2_euets_emissions(), co2_euets_installations(), co2_euets_price(), co2_euets_surrendered()

Examples

co2_euets_files()

EU ETS installation registry (historical 2012 snapshot)

Description

Returns the registry of stationary EU ETS installations with operator name, activity type, country, and permit details.

Usage

co2_euets_installations(country = NULL, refresh = FALSE)

Arguments

Details

Vintage warning: the only bulk installation registry DG CLIMA publishes is a Union Registry snapshot dated 28 August 2012 (Phase 2). It predates every installation added since, and permit statuses have not been updated. For current installation-level detail, use the identifier columns returned by co2_euets_emissions(), which come from the latest annual verified-emissions file.

Value

A data frame.

See Also

Other EU ETS: co2_euets_allocations(), co2_euets_emissions(), co2_euets_files(), co2_euets_price(), co2_euets_surrendered()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  inst <- co2_euets_installations(country = "PL")
})
options(op)

EU ETS allowance (EUA) auction settlement prices

Description

Fetches EU Allowance (EUA) primary-auction settlement prices from the EEX public auction report. Auctions are held several times per week; each year's file accumulates all auctions for that year.

Usage

co2_euets_price(from = NULL, to = NULL, year = NULL, refresh = FALSE)

Arguments

Value

A data frame with date, auction_name, contract, status, price_eur, min_bid_eur, max_bid_eur, volume_t.

See Also

Other EU ETS: co2_euets_allocations(), co2_euets_emissions(), co2_euets_files(), co2_euets_installations(), co2_euets_surrendered()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  prices <- co2_euets_price(year = 2025)
})
options(op)

EU ETS compliance status and cumulative surrendered units

Description

Returns cumulative total surrendered allowances per installation, compliance code, and account closure date. Per-year surrender events require the EUTL transaction log ZIP, which is deferred to v0.2.0 because it is ~1.5 GB uncompressed and requires LZMA extraction.

Usage

co2_euets_surrendered(country = NULL, file_year = NULL, refresh = FALSE)

Arguments

Value

A data frame with country, installation_id, installation_name, compliance_code, compliance_status, total_verified_emissions, total_surrendered_allowances, year_of_first_emissions, year_of_last_emissions, account_closure.

See Also

Other EU ETS: co2_euets_allocations(), co2_euets_emissions(), co2_euets_files(), co2_euets_installations(), co2_euets_price()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  comp <- co2_euets_surrendered(country = "FR")
})
options(op)

ICAP Allowance Price Explorer

Description

Fetches allowance prices across 20+ Emissions Trading Systems from the International Carbon Action Partnership (ICAP) Allowance Price Explorer. Covers EU ETS, UK ETS, California, RGGI, New Zealand, Korea, and other jurisdictions with auction and secondary-market prices where available.

Usage

co2_icap_prices(jurisdiction = NULL, include_download = FALSE, refresh = FALSE)

Arguments

Value

A data frame with date, jurisdiction, market_type ("primary" auction or "secondary"), price, and currency.

See Also

Other aggregators: co2_ecp_prices(), co2_icap_systems(), co2_rff_pricing(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
prices <- co2_icap_prices(jurisdiction = "EU ETS")
options(op)

ICAP systems available

Description

Lists the emissions trading systems carried by the ICAP Allowance Price Explorer, with the date range and number of observations for each. Use this to find the exact jurisdiction names accepted by co2_icap_prices().

Usage

co2_icap_systems(include_download = FALSE, refresh = FALSE)

Arguments

Value

A data frame with jurisdiction, currency, market_type, first_date, last_date, and n_obs.

See Also

Other aggregators: co2_ecp_prices(), co2_icap_prices(), co2_rff_pricing(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
co2_icap_systems()
options(op)

List supported carbon markets

Description

Returns a data frame of the carbon markets (compliance and voluntary) supported by this package, with coverage metadata.

Usage

co2_markets(type = c("all", "compliance", "voluntary"))

Arguments

Value

A data frame with columns market, name, type, coverage_start, jurisdiction, function_name, and notes.

Examples

co2_markets()
co2_markets(type = "compliance")

CarbonPlan OffsetsDB (via S3 parquet)

Description

Fetches the CarbonPlan OffsetsDB daily snapshots of voluntary carbon market projects and credits, stored as Parquet in a public S3 bucket. Covers Verra, ART TREES, Gold Standard, American Carbon Registry, and Climate Action Reserve.

Usage

co2_offsets_db(
  kind = c("projects", "credits"),
  date = NULL,
  max_lookback = 180L,
  refresh = FALSE
)

Arguments

Details

The CarbonPlan REST API at offsets-db-api.carbonplan.org was deprecated; this function uses the S3 bucket directly. Parquet reading requires an installed Parquet reader; the arrow package is the recommended suggest.

Value

A file path to the downloaded Parquet file. The caller must have arrow or nanoparquet installed to read it.

See Also

Other voluntary markets: co2_cad_trust(), co2_vrod()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  path <- co2_offsets_db("projects")
  if (requireNamespace("arrow", quietly = TRUE)) {
  df <- arrow::read_parquet(path)
  }
})
options(op)

RFF World Carbon Pricing Database

Description

Fetches the Dolphin-Pollitt-Newbery World Carbon Pricing Database for one country: national-level carbon pricing with CO2 tax and ETS instruments harmonised by IPCC sector across 200+ jurisdictions.

Usage

co2_rff_pricing(country, version = "v2025.0.0", refresh = FALSE)

Arguments

Details

On 30 May 2026 the maintainer stopped distributing WCPD through GitHub and stripped the data files from the default branch; new releases moved to https://worldcarbonpricing.org behind an emailed download token. This function therefore reads the last openly published snapshot, the v2025.0.0 tag, which remains available and covers 1990 to 2023. For newer vintages, request access on the WCPD site. For the companion emissions-weighted carbon price, which is still served openly, see co2_ecp_prices().

Value

A data frame of annual carbon prices by IPCC sector code.

References

Dolphin, G. G., Pollitt, M. G. and Newbery, D. M. (2020). "The political economy of carbon pricing: a panel analysis." Oxford Economic Papers, 72(2), 472–500. https://doi.org/10.1093/oep/gpz042

See Also

Other aggregators: co2_ecp_prices(), co2_icap_prices(), co2_icap_systems(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  uk <- co2_rff_pricing("United_Kingdom")
})
options(op)

RGGI allowance distribution by state and year

Description

Fetches the Regional Greenhouse Gas Initiative (RGGI) annual CO2 allowance distribution table from the public RGGI website. Covers 11 participating US states from 2009 onwards.

Usage

co2_rggi_allowances(year = NULL, refresh = FALSE)

Arguments

Details

Auction clearing prices are NOT returned here because RGGI publishes them only as per-auction PDFs (no CSV aggregation exists). For RGGI prices, use co2_icap_prices() with jurisdiction = "Regional Greenhouse Gas Initiative".

Value

A data frame of allowance distribution by state.

See Also

Other compliance markets: co2_california_caps(), co2_california_prices(), co2_rggi_state_proceeds(), co2_ukets(), co2_ukets_allocations()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  a <- co2_rggi_allowances(year = 2026)
})
options(op)

RGGI cumulative state proceeds by auction

Description

Fetches cumulative auction proceeds time series for one RGGI state, indexed by auction number. Derived from the per-state XLSX files on rggi.org. Combining all states gives the full RGGI auction time series.

Usage

co2_rggi_state_proceeds(state, refresh = FALSE)

Arguments

Value

A data frame.

See Also

Other compliance markets: co2_california_caps(), co2_california_prices(), co2_rggi_allowances(), co2_ukets(), co2_ukets_allocations()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  ny <- co2_rggi_state_proceeds("NY")
})
options(op)

UK ETS verified emissions and surrenders

Description

Fetches the UK Emissions Trading Scheme Section 4 compliance report (verified emissions and allowance surrenders per account per scheme year), published annually by the UK Emissions Trading Registry after the 30 April reconciliation deadline.

Usage

co2_ukets(refresh = FALSE)

Arguments

Value

A data frame with one row per account-year.

See Also

Other compliance markets: co2_california_caps(), co2_california_prices(), co2_rggi_allowances(), co2_rggi_state_proceeds(), co2_ukets_allocations()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  uk <- co2_ukets()
})
options(op)

UK ETS free allocations

Description

Fetches the UK ETS free-allocation table for stationary installations (OHA) published by DESNZ on GOV.UK. Filename includes a media GUID that changes when DESNZ republishes, so the package scrapes the stable publications landing page.

Usage

co2_ukets_allocations(sector = c("installations", "aviation"), refresh = FALSE)

Arguments

Value

A data frame.

See Also

Other compliance markets: co2_california_caps(), co2_california_prices(), co2_rggi_allowances(), co2_rggi_state_proceeds(), co2_ukets()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  alloc <- co2_ukets_allocations()
})
options(op)

Berkeley Voluntary Registry Offsets Database

Description

Fetches the Berkeley GSPP Voluntary Registry Offsets Database, an aggregator of Verra, Gold Standard, ACR, CAR, and ART TREES project registrations and issuances. Released bimonthly under CC BY 4.0.

Usage

co2_vrod(sheet = "PROJECTS", refresh = FALSE)

Arguments

Value

A data frame of project-level data.

See Also

Other voluntary markets: co2_cad_trust(), co2_offsets_db()

Examples

op <- options(carbondata.cache_dir = tempdir())
try({
  vrod <- co2_vrod()
})
options(op)

World Bank Carbon Pricing Dashboard

Description

Reads the World Bank Carbon Pricing Dashboard Excel file, which covers 70+ carbon pricing initiatives worldwide (carbon taxes and emissions trading systems) with price, coverage, and revenue data.

Usage

co2_world_bank(path = NULL, sheet = 1L, refresh = FALSE)

Arguments

Details

Manual download may be required. Since 2026 the dashboard host rejects non-browser HTTP clients (every request returns HTTP 403, regardless of user agent), so this function often cannot fetch the file for you. When the automatic download fails it reports the direct file URL: download that in a browser and pass the local path via path. The file is republished roughly twice a year, so a manual copy stays current for months.

Value

A data frame.

See Also

Other aggregators: co2_ecp_prices(), co2_icap_prices(), co2_icap_systems(), co2_rff_pricing()

Examples

op <- options(carbondata.cache_dir = tempdir())
wb <- try(co2_world_bank(), silent = TRUE)
options(op)