DSIR

Step 1: Search for an indicator

gho_indicators("UHC") |> head()

Pick an IndicatorCode from the result — this is the value you pass to gho_data() in the next step.

Step 2: Fetch the data

uhc <- gho_data(
  indicator    = "UHC_INDEX_REPORTED",
  spatial_type = "country",
  area         = wpro_cty,
  year_from    = 2015
)

uhc |> glimpse()

Note that area accepts long ISO3 vectors — here we fetch all 28 WPR countries in one call.

Step 3: Clean the raw response

gho_clean() produces the unified DSIR cleaned-indicator schema — the same 15-column shape as sdg_clean(). Columns include source ("gho"), id, indicator, location, iso3, location_name (resolved for known locations), year, value, value_num, low, high, series (resolved for known locations), and the three optional GHO dimensions dim1–dim3. Columns absent from the raw response are filled with typed NA.

uhc_clean <- gho_clean(uhc)
uhc_clean

Single panel: theme_dsi()

theme_dsi() keeps the chart chrome minimal — a half-frame axis, light grid lines, and the WHO-blue accent on the axis line. By default the grid runs in both directions; pass grid = "y" for the minimalist horizontal-only look.

uhc_clean |>
  filter(iso3 %in% c("AUS", "CHN", "PHL", "FJI")) |>
  left_join(who_countries, by = "iso3") |>
  ggplot(aes(x = year, y = value_num, group = iso3, color = name_short)) +
  geom_line(linewidth = .8) +
  geom_point(size = 1.8) +
  theme_dsi() +
  labs(
    title    = "UHC Service Coverage Index, selected WPR Member States",
    subtitle = "2015 onwards",
    x = NULL, y = "SCI", color = NULL
  )

For bar charts, pair theme_dsi() with scale_y_dsi_col() (or scale_x_dsi_col() when value is mapped to x) — these are thin wrappers around scale_*_continuous() that remove the lower axis expansion, so columns sit flush with the axis instead of floating above it.

uhc_clean |>
  filter(year == max(year)) |>
  left_join(who_countries, by = "iso3") |>
  arrange(desc(value_num)) |>
  head(10) |>
  ggplot(aes(reorder(name_short, value_num), value_num)) +
  geom_col(fill = "#0093D5") +
  coord_flip() +
  scale_y_dsi_col() +
  theme_dsi(grid = "x") +
  labs(
    title    = "UHC Service Coverage Index, top 10 WPR Member States",
    subtitle = "Latest available year",
    x = NULL, y = "SCI"
  )

Faceted: theme_dsi_facet()

When the same chart is split across many small panels, the half-frame look becomes visually noisy — the accent-blue axis line repeats across every facet. theme_dsi_facet() switches to a full panel border, adds a light grey strip background to clearly mark each facet’s label, and introduces panel spacing so adjacent panels don’t run together.

uhc_clean |>
  left_join(who_countries, by = "iso3") |>
  filter(is_pic) |>
  ggplot(aes(x = year, y = value_num)) +
  geom_line(color = "#0093D5", linewidth = 0.8) +
  geom_point(color = "#0093D5", size = 1.5) +
  facet_wrap(~ name_short, ncol = 4) +
  theme_dsi_facet() +
  labs(
    title    = "UHC Service Coverage Index, Pacific Island Countries",
    subtitle = "Each panel shows one country's trajectory",
    x = NULL, y = "SCI"
  )

The strip_fill argument lets you change the strip background colour for emphasis — for example, a light-blue tone derived from the WHO accent for a deliverable where the strips themselves carry meaning:

uhc_clean |>
  left_join(who_countries, by = "iso3") |>
  filter(is_pic) |>
  ggplot(aes(x = year, y = value_num)) +
  geom_line(color = "#0093D5", linewidth = 0.8) +
  facet_wrap(~ name_short, ncol = 4) +
  theme_dsi_facet(strip_fill = "#E5F4FB") +
  labs(title = "UHC SCI, PIC — with custom strip colour",
       x = NULL, y = "SCI")

Keeping named SDG dimensions

SDG dimensions are named fields in sdg$dimensions, not positional GHO dimensions. The compact 15-column output omits them. For disaggregated analysis, retain them explicitly:

raw <- sdg_data("3.8.2", area = "PHL")
unique(raw$dimensions)
sdg_clean(raw, keep_dimensions = TRUE)

This appends character columns such as dim_age, dim_location, dim_sex, dim_reporting_type, dim_quantile, and dim_type_of_household. Names depend on the dimensions actually returned by the API. Codes are unchanged; absent categories are not assigned total-population codes. Use keep_metadata = TRUE to also retain units and other attributes in the cleaned table.

Select a series and strata with the exact source names and codes:

sdg_data(
  "3.8.2", area = "PHL",
  series = "SH_OOP_XPD_EARNNET40",
  dimensions = list(
    Age = "ALLAGE", Location = "ALLAREA", Sex = "BOTHSEX",
    Quantile = "_T", Type_of_household = "_T"
  )
) |>
  sdg_clean(keep_dimensions = TRUE)

These filters run locally after pagination. Values within one dimension are OR-ed; different dimensions are AND-ed. An absent requested dimension warns and returns no rows instead of silently ignoring a population restriction.

The UN 3.8.2 catalogue checked on 2026-09-30 lists the revised 2025-definition series SH_OOP_XPD_EARNNET40. GHO’s FINANCIALHARDSHIP_PROPORTIONOFPOP additionally includes large and impoverishing expenditure components in Dim1. Those are not separate series in that UN catalogue and cannot be reconstructed by retaining SDG dimensions. See the WHO definition and components.

Showing dimension meaning and source context

Use sdg_dimensions() to see the official categories and labels for each series. This does not download observations, and the listed categories need not occur in every country:

sdg_dimensions("3.8.2", include_attributes = TRUE)

The code column contains the JSON API codes used for filtering; the sdmx column is an alternative representation. kind distinguishes dimensions from attributes such as units and nature.

To preserve source context as well as population dimensions:

detailed <- sdg_clean(raw, keep_dimensions = TRUE, keep_metadata = TRUE)
detailed |>
  select(any_of(c("iso3", "year", "value_num", "attr_units", "attr_nature", "data_source")))
head(detailed$footnotes, 1L)

keep_metadata retains all returned attributes as attr_* columns, plus source, time detail/coverage, base period, value type, and geographic information URL. Footnotes and all linked indicator, goal, and target codes are list-columns, so multiple entries are preserved. Use RDS for storage when retaining this structure.

For GHO, show each positional dimension’s type directly:

This financial-hardship code is not in the public xMart directory as of 2026-10-06. Select the legacy provider explicitly for this example.

gho_detailed <- gho_data("FINANCIALHARDSHIP_PROPORTIONOFPOP", area = "PHL",
                         backend = "legacy") |>
  gho_clean(keep_dimensions = TRUE, keep_metadata = TRUE)
gho_detailed |>
  select(provider, iso3, year, value_num, dim1_type, dim1, dim2_type, dim2)

Types are taken from each observation’s Dim1Type–Dim3Type. They are never guessed from a code prefix or assumed constant for the whole indicator. GHO metadata includes the retrieval provider, original source codes, observation identifiers, comments (in footnotes), location/time types, parent locations, update timestamps, and time intervals. Neither optional flag changes the default 15-column output.

sdg_data() validates declared pagination and total row counts before local filtering. An incomplete download returns no rows with a warning. sdg_coverage() retains such warnings and accepts series and dimensions filters; without filters, its observation counts combine all strata in each location and series.

Combining GHO and SDG with bind_indicators()

When an analysis pulls indicators from both sources, bind_indicators() stacks any number of cleaned tibbles into one. The source column ("gho" / "sdg") lets you filter or facet by origin without remembering which frame came from which API.

Additional columns, including named SDG dimensions, are retained; inputs without those columns receive typed missing values. Binding rows does not harmonise codes or definitions across the sources.

# Two indicators on the same topic from different APIs:
#   GHO NCDMORT3070 (probability of premature NCD mortality)
#   SDG 3.4.1       (mortality rate from NCDs)
gho_ncd <- gho_data("NCDMORT3070", area = wpro_cty) |> gho_clean()
sdg_ncd <- sdg_data("3.4.1",        area = wpro_cty) |> sdg_clean()
bind_indicators(gho_ncd, sdg_ncd) |> glimpse()

Exploring series with sdg_coverage()

A single SDG indicator often contains several series — for example different vaccines, sex strata, or causes of death — each with its own country and year coverage. Indicator "3.b.1" (vaccine coverage) is a clear case: it is published as four separate series (DTP3, MCV2, PCV3, HPV), and the year coverage of the newer vaccines is much shorter than that of DTP3.

sdg_coverage() summarises the year range and observation count per (location, series), so you can inspect what series exist and how each is covered before deciding which one to analyse.

sdg_coverage("3.b.1", area = c("156", "608"))
#>   location series      year_min year_max n_obs
#> 1 156      SH_ACS_DTP3     2000     2023    24
#> 2 156      SH_ACS_HPV      2018     2023     6
#> 3 156      SH_ACS_MCV2     2000     2023    24
#> 4 156      SH_ACS_PCV3     2017     2023     7
#> 5 608      SH_ACS_DTP3     2000     2023    24
#> 6 608      SH_ACS_HPV      2017     2023     7
#> 7 608      SH_ACS_MCV2     2000     2023    24
#> 8 608      SH_ACS_PCV3     2014     2023    10

Note that DSIR intentionally does not provide SDG analogues of gho_has_data() and gho_count(). SDG data is generally complete enough that those screening helpers add little value — the more useful pre-analysis question for SDG is “which series are available?”, which is what sdg_coverage() answers.