*! version 2.0.0 24Jan2026

get_sdmx — Low-level SDMX data fetching

Syntax

get_sdmx,
indicator(string)
[agency(string)
dataflow(string)
countries(string)
filter(string)
detail(string)
format(string)
labels(string)
year(string)
start_period(string)
end_period(string)
filename(string)
wide
clear
nofilter
retry(int)
cache
country_names
verbose
debug
trace
]

Description

get_sdmx is a low-level function for downloading data from any SDMX-compliant
API (World Bank Open Data, UNICEF Data Warehouse, etc.).
It handles:

• Automatic or manual dataflow detection

• Intelligent query filter engine (dimension extraction from schemas)

• Paging and retry logic with exponential backoff

• Dynamic User-Agent header for API identification

• Fallback from curl to copy if primary fetch fails

• Schema caching for improved performance

Most users should use unicefdata instead, which wraps this function.
get_sdmx is for advanced users requiring direct SDMX API access.

Default Behavior

Summary of defaults when options are omitted:

Option Default Value

agency() UNICEF

countries() All countries (empty)

year() All available years

format() csv

labels() id (codes only)

detail() data (fetch observations)

retry() 3 attempts

wide Long format (rows per observation)

clear No clear (preserve existing data)

Wide format output:

• Year columns are prefixed with yr (e.g., yr2018, yr2019)

• Context/dimension variables appear before year columns

• All variable names are lowercase with descriptive labels

Options

Required

indicator(string) is required. Specifies the indicator code(s)
to fetch. Examples: SP.POP.TOTL, CME_MRY0T4, NT_ANT_WHZ_PO2.

Data Source

agency(string) specifies the data provider agency. Default is UNICEF.
Other options: WB (World Bank), WHO, IMF, etc.
Ignored if dataflow() is specified.

dataflow(string) manually specifies the dataflow to bypass auto-detection.
Format: AGENCY.DATAFLOW_CODE (e.g., UNICEF.CME, WB.DF_WBOPENDATA).
Use this when the dataflow is known to skip YAML lookup overhead.

Filtering

countries(string) specifies ISO3 country code(s) to filter. Optional.
Format: Single code ("BRA") or plus-separated list ("BRA+MEX+ARG").
Special: "all" or empty = fetch all countries. Default is empty (all countries).

filter(string) specifies a dimension filter vector (space-separated values).
Format: "sex_val age_val wealth_val residence_val maternal_edu_val"
Example: "_T Y0T4 Q1 _T _T"
Used by unicefdata wrapper to build efficient URLs. Tokens may include +
to request multiple members within a dimension.

nofilter fetches all disaggregations (slower). By default, efficient
filtering is used (totals only).

year(string) specifies year(s) to retrieve. Supports three formats:

Single year: year(2020) - fetch only 2020

Range: year(2015:2023) - fetch years 2015 through 2023

List: year(2015,2018,2020) - fetch specific non-contiguous years

If omitted, all available years are retrieved. Overrides start_period()
and end_period() if specified.

start_period(string) and end_period(string) restrict time range.
Format: YYYY (e.g., 2015). Ignored if year() is specified.

Output

detail(string) specifies the query type. Default is data.
Options: data (fetch observations), structure (fetch schema/DSD).

format(string) specifies API response format. Default is csv.
Options: csv, sdmx-xml, sdmx-json, sdmx-compact-2.1.

labels(string) specifies column labels format. Default is id.
Options: both (codes and names), id (codes only), none.

filename(string) specifies file path for saving downloaded CSV.
When specified: saves API response to this file, returns path in r(datafile).
When omitted: creates tempfile, loads data directly into memory.
Example: filename("C:/temp/data.csv")

wide returns data in wide format using csv-ts API output.
By default, data is returned in long format (observations in rows).
When wide is specified: uses format=csv-ts for transposed format,
with years as columns (prefixed yr), series metadata as rows.
Significantly faster than Stata reshape (~1-2 seconds vs 5-10 seconds).
Useful when you want to work with year columns directly or reshape within your domain logic.

clear clears existing data in memory before loading new data from API.
Default is noclear (preserves existing data). Use clear to replace data
completely. This option follows Stata convention (insheet clear).
Example: get_sdmx, indicator(CME_MRY0T4) clear

country_names adds a country name column to the output. Default is on.

Performance

retry(int) specifies number of retry attempts on failure. Default is 3.

cache enables schema caching for improved performance on subsequent calls.
First call: ~2.2 seconds (API + schema fetch). Cached call: ~0.13 seconds.

Debugging

verbose displays progress messages during fetch.

debug displays maximum debugging information including:
system network configuration, full URL details, detailed error codes,
API response preview, and network diagnostics.

trace enables Stata trace on network calls.
Use with set tracedepth 1 for deeper inspection.
Usually combined with debug for maximum detail.

Stored results

get_sdmx stores the following in r():

r(csv_file) path to fetched CSV file

r(datafile) path to data file (when filename() used)

r(n_obs) number of observations returned

r(n_vars) number of variables returned

r(time_series) comma-separated list of time periods

r(api_url) final API URL used for fetch

r(dataflow) resolved dataflow ID

Examples

Fetch UNICEF child mortality indicator (auto-detect dataflow):

. get_sdmx, indicator(CME_MRY0T4)

Fetch with manual dataflow to skip YAML lookup:

. get_sdmx, indicator(CME_MRY0T4) dataflow(UNICEF.CME)

Fetch with country filter:

. get_sdmx, indicator(CME_MRY0T4) countries(BRA+MEX+ARG)

Fetch with time period and verbose output:

. get_sdmx, indicator(CME_MRY0T4) year(2015:2023) verbose

Save to file instead of loading into memory:

. get_sdmx, indicator(CME_MRY0T4) filename("C:/temp/cme_data.csv")

Fetch data in wide format (years as columns):

. get_sdmx, indicator(CME_MRY0T4) countries(USA+CAN+MEX) wide

Fetch with wide format and clear existing data:

. get_sdmx, indicator(CME_MRY0T4) wide clear

Fetch with caching for repeated calls:

. get_sdmx, indicator(CME_MRY0T4) cache

Debug connection issues:

. get_sdmx, indicator(CME_MRY0T4) debug verbose

Version history

v1.3.3 (20Jan2026) - Wide format improvements: all variable names lowercase,
all variables have descriptive labels, context/dimension variables ordered before year columns.

v1.3.2 (20Jan2026) - Added wide and clear options.
wide uses csv-ts API format for transposed output (1-2s vs 5-10s reshape).
clear controls whether to clear existing data before loading (follows Stata convention).

v1.2.0 (18Jan2026) - Added filename() parameter for flexible data handling.
When specified, saves CSV to file and lets caller handle import.
When omitted, creates tempfile and loads data directly into memory.

v1.1.0 (17Jan2026) - Integrated intelligent query filter engine.
Auto-detects query mode, extracts dimensions from dataflow schemas,
enhanced verbose output showing query mode and filter dimensions.

v1.0.0 - Initial release with paging, retry logic, caching, and multi-agency support.

Author

João Pedro Azevedo, UNICEF

https://jpazvd.github.io

See also

unicefdata (main user-facing command)

unicefdata_sync (metadata synchronization)

unicefdata_examples (gallery of examples)