Skip to contents

Fetch SDG Data

Source: R/sdg.R
sdg_data.Rd

Retrieves data for one or more SDG indicators from the UN SDG API, with optional filters by area, year, series, and named dimensions.

Usage 

sdg_data(
  indicator,
  area = NULL,
  year_from = NULL,
  year_to = NULL,
  page_size = 1000L,
  series = NULL,
  dimensions = NULL
)

Arguments

indicator

Character vector of indicator codes (e.g. "1.1.1"). Use sdg_indicators() to find codes.

area

Character vector of country/area codes. Accepts either ISO3 codes (e.g. c("PHL", "FRA")) — converted automatically via iso3_to_m49() — or UN M49 numeric codes (e.g. c("608", "250")) as returned by sdg_areas(). Do not mix the two formats in a single call. Default NULL returns all areas.

year_from

Numeric. Start year filter (inclusive). Default NULL.

year_to

Numeric. End year filter (inclusive). Default NULL.

page_size

Integer. Number of records per page. Default 1000, maximum 10000.

series

Optional character vector of series codes to keep. Default NULL keeps all series. Applied client-side after all pages have been retrieved.

dimensions

Optional named list of character vectors, using the exact names and codes in the returned dimensions column, for example list(Sex = "BOTHSEX", Quantile = "_T"). Values within a dimension are OR-ed; different dimensions are AND-ed. Matching is case-sensitive. Missing dimension values do not match. An absent requested dimension warns and returns no rows. Default NULL keeps all strata. Like year and series filters, these filters run client-side and do not reduce the number of downloaded pages.

Value

A tibble of indicator observations, or an empty tibble when the service is unreachable or there are no matching rows. The raw dimensions and attributes columns retain the API's named breakdowns and attributes (usually packed data-frame columns). Inspect unique(df$dimensions) to discover observed strata. Use sdg_clean(df, keep_dimensions = TRUE) to retain named dimensions as flat columns when cleaning. If reported page numbers, page counts, or total row counts are inconsistent, warns and returns no rows. Counts are checked before local filters. Counts omitted by the API cannot be verified; a response without totalPages is treated as one page.

Retrieval metadata

Downloads and directories retain their existing classes and columns. dsir_metadata(x)$sources records the actual backend, endpoint, UTC retrieved_at, retrieval status, cache use, source record count, reported API version and release. Unknown versions and times remain NA. Each source row includes its own server query. query records the public selection, including local filters and reference-country/year restrictions. result describes the function's original return; current is computed from the supplied object. Source counts precede local filtering and GHE measure pivoting, so they can differ from returned row counts.

Result status distinguishes success, empty, failed, incomplete, invalid, partial and unverified. Completeness concerns the requested retrieval, not global indicator coverage. It is NA when the response lacks sufficient completeness information. A successful HTTP response alone does not establish completeness of an observation download.

Cached records retain their original retrieval time and set cache_hit. A historical fallback uses retrieval_status = "bundled_snapshot" and retains the original collection date. It does not prove live availability. Failed SDG list requests still return NULL with a warning; NULL cannot carry metadata. Other empty failure results record no successful retrieval time. Existing WHO who_provenance and catalog_snapshot attributes remain available for compatibility.

Cleaners preserve acquisition metadata even for empty input. This is independent of keep_metadata, which controls optional data columns. as_dsir_data() also retains sources, query and result. These are historical acquisition records, not an audit of arbitrary changes to a plain tibble. Use the S3 object's processing status to track supported transformations. saveRDS() preserves attributes; CSV does not.

Cleaning records live in cleaning, also for output = "tibble" and user-supplied input without acquisition records. They contain the cleaner, package version, UTC cleaning time, input/output sizes and columns, options, and a profile of semantic fields. Each profile records its retained column (or NA), distinct count including missing values, missing count and its constant value, if any. Varying omitted values are not stored row by row. Recorded aliases link equivalent core and named dimensions. Cleaning time never substitutes for retrieval time. These records describe the cleaning input; current coverage and subsequent field status remain separate.

See also

sdg_indicators(), sdg_areas(), sdg_clean(), sdg_dimensions(), iso3_to_m49().

Examples 

# \donttest{
# One indicator, one country — the typical entry point
sdg_data("1.1.1", area = "PHL")

# Specific area and year range (M49 code)
sdg_data("3.2.1", area = "156", year_from = 2015, year_to = 2023)

# ISO3 codes work directly — DSIR's regional vectors can be passed in
sdg_data("3.4.1", area = c("PHL", "FRA", "JPN"))
# }