importData: Import a Flat OECD Dataset

In OECDdata: Fast and Friendly Access to OECD Data

Import a Flat OECD Dataset

Description

Import a Flat OECD Dataset.

Usage

importData(OECDDatasetCode, filters = NULL)

Arguments

OECDDatasetCode

A catalogue-resolved short code such as "CLI", a terminal ID such as "DF_CLI", a complete dataflow ID such as "DSD_STES@DF_CLI", or a qualified reference "OECD.SDD.STES,DSD_STES@DF_CLI" with an optional numeric version. Short codes are accepted only when resolution is unambiguous. An omitted version, "latest" or "+" selects the latest stable structure. See oecdDataset for resolution rules.

filters

NULL for all observations, or a non-empty named list of character/numeric vectors. Names identify dimensions, except for the optional reserved .dataset block described below. Multiple codes within a dimension are combined with OR; dimensions are combined with AND. A time vector is interpreted as an inclusive range from its minimum to its maximum, not as a discrete set of requested dates. See Details.

Details

The optional .dataset block is a named list of agency, prefix and/or version identity selectors, with the same meaning as in oecdDataset. For example, list(.dataset = list(agency = "OECD.SDD.STES"), REF_AREA = "USA"). These selectors choose a dataset and are removed before dimension filtering. A selector-only block leaves all dimensions unrestricted. Conflicts with an explicit reference are errors. The Filters result attribute retains the original full list, including the selector block.

The structure is resolved before constructing the data query. Dimension names are matched case-insensitively; values must be valid literal codes with their original case. Leading zeros in identifiers are preserved. A single empty string selects all values of its dimension and produces a warning. Other missing or empty selections fail explicitly.

Common annual, quarterly, half-yearly, weekly, monthly and daily period formats are supported: YYYY, YYYY-Q1, YYYY-S1, YYYY-W01, YYYY-MM, and YYYY-MM-DD. Annual YYYY-A1 and monthly YYYY-M01 aliases are normalized. Use one granularity in a filter. Subdaily periods, custom calendars and mixed-granularity bounds are not supported.

The client downloads to disk and parses with data.table::fread. It does not aggregate, infer seasonal adjustment, rescale units, translate flags, or fill in a Cartesian product of missing observations. Duplicate observation keys, delete actions, unexpected response identities and malformed values fail rather than being silently repaired. HTTP 204 produces a typed empty result with a warning; HTTP errors, including 404, remain errors.

A pinned structure version does not freeze historical statistical revisions. Save an RDS snapshot when an exact data vintage is required.

Value

By default, a data.frame with classes OECDDataset and data.frame. Dimension columns are factors, value_ is a double, and flags_ contains the raw OBS_STATUS text, or an empty string if that attribute is absent. All other supplied statistical attributes are retained. Set return_data_table = TRUE for a data.table, and strings_as_factors = FALSE for character dimensions.

Attributes include RequestedDatasetCode (input reference), OECDDatasetCode (resolved exact reference), DownloadTime, SourceURL, Cached, Dimensions, OECDAttributes, and Filters. A cache hit preserves the original download time.

See Also

oecdDataset, oecdQuery, oecdStructure, importLabels, oecdOptions

Examples

x <- oecdExample()
names(x)
attr(x, "Dimensions")
if (interactive()) {
cli <- importData(OECDDatasetCode = "CLI",
  filters = list(REF_AREA = c("USA", "FRA"), FREQ = "M",
                 TIME_PERIOD = c("2023-01", "2023-12")))
}

OECDdata documentation built on Oct. 31, 2026, 1:07 a.m.