Package 'carbondata'

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 in v0.1.0)

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

...

Ignored.

Details

This function is a placeholder that errors with guidance. CAD Trust support is deferred to carbondata v0.2.0 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

refresh

Re-download? Default FALSE.

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())
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

refresh

Re-download? Default FALSE.

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())
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)

---

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,
  refresh = FALSE
)

Arguments

country	Optional character vector of two-letter registry codes to filter (e.g. c("DE", "FR", "PL")).
year	Optional integer vector of emissions years. When NULL, returns all years in the latest published file. Note that the file year (e.g. "2025") refers to publication year; emissions data covers calendar years up to publication year -1.
file_year	Publication year of the DG CLIMA file to use. Default is the latest year available in the package (see co2_euets_files()).
refresh	Logical. Re-download? Default FALSE.

Value

A data frame with country, installation_id, year, allocation_eua.

See Also

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

Examples

## Not run: 
# DG CLIMA file schema drifted in 2026; parser needs updating.
# Tracked at https://github.com/charlescoverdale/carbondata/issues
alloc <- co2_euets_allocations(country = "DE")

## End(Not run)

---

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,
  refresh = FALSE
)

Arguments

country	Optional character vector of two-letter registry codes to filter (e.g. c("DE", "FR", "PL")).
year	Optional integer vector of emissions years. When NULL, returns all years in the latest published file. Note that the file year (e.g. "2025") refers to publication year; emissions data covers calendar years up to publication year -1.
file_year	Publication year of the DG CLIMA file to use. Default is the latest year available in the package (see co2_euets_files()).
refresh	Logical. Re-download? Default FALSE.

Value

A data frame with columns country, installation_id, installation_name, activity, 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

## Not run: 
# DG CLIMA file schema drifted in 2026; parser needs updating.
# Tracked at https://github.com/charlescoverdale/carbondata/issues
de <- co2_euets_emissions(country = "DE")

## End(Not run)

---

List the EU ETS data file versions bundled with this package

Description

Returns a data frame of the DG CLIMA file vintages supported. When DG CLIMA publishes a newer file, upgrade the package.

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

Description

Returns the registry of stationary EU ETS installations with operator name, activity type, country, city, and permit details. Sourced from the DG CLIMA Union Registry snapshot.

Usage

co2_euets_installations(country = NULL, refresh = FALSE)

Arguments

country	Optional two-letter registry codes.
refresh	Re-download? Default FALSE.

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())
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

from, to	Optional character or Date. Date range.
year	Optional integer year. If supplied, only the file for that year is fetched (faster than from/to).
refresh	Re-download? Default FALSE.

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())
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

country	Optional two-letter registry codes.
file_year	Publication year of the compliance file. Default is the latest in the package.
refresh	Re-download? Default FALSE.

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())
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, refresh = FALSE)

Arguments

jurisdiction	Optional character vector. Filter by jurisdiction name (e.g. c("Regional Greenhouse Gas Initiative", "EU ETS")). When NULL, returns all.
refresh	Re-download? Default FALSE.

Value

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

See Also

Other aggregators: co2_rff_pricing(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
prices <- co2_icap_prices(jurisdiction = "EU ETS")
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

type	Character. One of "all" (default), "compliance", or "voluntary".

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, refresh = FALSE)

Arguments

kind	Character. "projects" (default) or "credits".
date	Optional character. ISO date of the snapshot to fetch (must be a day CarbonPlan published; the function walks backwards from this date up to 7 days). Default Sys.Date().
refresh	Re-download? Default FALSE.

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())
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. Covers national-level carbon pricing from 1989 to present, with CO2 tax and ETS instruments harmonised across 200+ jurisdictions.

Usage

co2_rff_pricing(country, version = "v2026.1", refresh = FALSE)

Arguments

country	Character. Country name using underscores (e.g. "United_Kingdom", "Germany", "Antigua_and_Barbuda").
version	Character. Dataset version folder. Default "v2026.1".
refresh	Re-download? Default FALSE.

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_icap_prices(), co2_world_bank()

Examples

op <- options(carbondata.cache_dir = tempdir())
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

year	Integer year (2009-present). Default is the current year.
refresh	Re-download? Default FALSE.

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())
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

state	Two-letter state code (one of: CT, DE, MA, MD, ME, NH, NJ, NY, RI, VA, VT).
refresh	Re-download? Default FALSE.

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())
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

refresh

Re-download? Default FALSE.

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())
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

sector	Character. "installations" (default) for stationary installations, "aviation" for aviation allocations.
refresh	Re-download? Default FALSE.

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())
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(refresh = FALSE)

Arguments

refresh

Re-download? Default FALSE. Each release has a date-stamped filename; the package scrapes the landing page to find the latest release on each call unless a cached copy exists.

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())
vrod <- co2_vrod()
options(op)

---

World Bank Carbon Pricing Dashboard

Description

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

Usage

co2_world_bank(refresh = FALSE)

Arguments

refresh

Re-download? Default FALSE.

Details

The World Bank publishes a dated file every 6-12 months. This function scrapes the landing page to find the latest release.

Value

A data frame.

See Also

Other aggregators: co2_icap_prices(), co2_rff_pricing()

Examples

op <- options(carbondata.cache_dir = tempdir())
wb <- co2_world_bank()
options(op)

---