wb-api-tools 0.2.0rc1

World Bank Open Data helpers — Python library + CLI mirroring the Stata wbopendata surface (discovery, data, country-context, multilingual, linewrap).

wb-api-repo

World Bank Open Data helpers in Python (library + CLI) and Stata (wbopendata ado package). Two surfaces over the same WB API v2, with a shared YAML metadata cache so discovery commands stay fast and offline-safe.

Python package: wb-api-tools on PyPI — pip install wb-api-tools (live release version shown in the PyPI badge above). Parallel v0.x track to the upstream wbopendata-dev Stata Journal lineage (v18.x).

What's here

Surface	Entry point	Reference
Python library	wb_api_tools.{discovery,data,text} (re-exported at package root)	docs/PYTHON_USER_GUIDE.md
Python CLI	wb-api-tools <subcmd> (after install) or python -m wb_api_tools <subcmd>	--help on every subcommand
Stata package	src/w/wbopendata.ado (v17.4.0)	help wbopendata in Stata, or src/w/wbopendata.sthlp
YAML metadata cache	~/.cache/wbopendata/_wbopendata_{indicators,sources,topics}.yaml (XDG-aware)	populated by wb-api-tools sync

Install

From PyPI (once published — see pyproject.toml for the canonical name):

pip install wb-api-tools

From a git checkout (dev mode):

git clone https://github.com/jpazvd/wb-api-repo.git
cd wb-api-repo
pip install -e ".[test]"

Requires Python 3.11+. The Stata package is loaded by adding src/w/ and src/_/ to Stata's adopath (or installed via net install once an SSC release lands).

Quick start

The repo ships with a runnable 7-section walkthrough that exercises the whole Python surface (discovery, live describe, get_data flag matrix, enrich_country_context, wb_text formats):

PYTHONIOENCODING=utf-8 python examples/demo_pr_b_c.py

Captured transcript: docs/PYTHON_DEMO.md.

Python CLI

After pip install, use the wb-api-tools console script (or python -m wb_api_tools if PATH doesn't include scripts). Each subcommand has --help for full flag descriptions.

Subcommand	Purpose
countries	Fetch country metadata
indicators	Fetch indicator metadata (legacy CSV/parquet/yaml dump)
data	Fetch indicator data; --no-basic skips country-context auto-merge, --geo adds capital/lat/lon, --language es switches the API path
sources	List WB data sources (--all for the full set)
alltopics	List all WB topic categories
info <id>	Show full metadata for one indicator (from YAML cache)
describe <id>	Fetch fresh metadata for one indicator (live API; --language supported)
search [term]	Paginated indicator search; --source, --topic, --field, --exact
sync	Populate / refresh the YAML metadata cache from the live WB API

Example:

wb-api-tools data \
    --indicators SP.POP.TOTL,NY.GDP.MKTP.CD \
    --countries "BRA;USA;IND" \
    --date 2010:2020 \
    --geo --long --out _data/wb/pop_gdp_long.csv

Output is written to --out (.csv / .parquet / .yaml / .yml) or printed as a preview if --out is omitted.

Python library

After pip install, the package is importable directly — no sys.path hacks needed:

import wb_api_tools as wb

wb.search("poverty headcount", limit=5)
df = wb.get_data(["SP.POP.TOTL"], "BRA;USA;IND", date="2020", geo=True)
wb.wrap("long indicator title ...", width=60, fmt="stack")   # for Stata graph title()

Full reference: docs/PYTHON_USER_GUIDE.md (library + CLI + Stata-parity table).

Stata package

src/w/wbopendata.ado is the v17.4.0 dispatcher; current Phase-0-through-6 surface mirrors the Python library:

• wbopendata, sources / allsources / alltopics / info / search / describe discovery commands
• wbopendata, indicator(X) clear data fetch with noBASIC, geo, language(es), cache(days), sync
• linewrap(W) maxlength(N) linewrapformat(stack|newline|lines|smcl) for graph-title and SMCL formatting

Open src/w/wbopendata.sthlp in Stata's viewer or run help wbopendata once the package is on the adopath. The Python-side docs/PYTHON_USER_GUIDE.md §5 has a row-by-row Stata ↔ Python parity table.

YAML metadata cache

The offline metadata cache lives in a per-user XDG-aware directory (typically ~/.cache/wbopendata/ on POSIX or ~/AppData/Local/wbopendata/ on Windows; override with $WBOPENDATA_YAML_DIR):

• _wbopendata_indicators.yaml — 29,511 indicators (~18 MB)
• _wbopendata_sources.yaml — 71 sources
• _wbopendata_topics.yaml — 21 topics

Discovery commands (info, search, sources, alltopics) read from this cache for microsecond lookups. After pip install, populate it once:

wb-api-tools sync                # download + write all three YAMLs (~10 min first time)
wb-api-tools sync --commit --tag # git-commit + tag (dev mode only)

A semi-monthly GitHub Action (.github/workflows/wb_metadata_nightly.yml — file name is historical; cron runs on the 1st and 15th of every month at 02:17 UTC, so 14–17 days apart depending on month length) keeps the repo-committed cache fresh. Manually triggerable via workflow_dispatch.

Documentation

• docs/PYTHON_USER_GUIDE.md — Python library + CLI reference (Stata .sthlp equivalent)
• docs/PYTHON_DEMO.md — captured live-API transcript from the 7-section walkthrough
• docs/EXAMPLES.md — end-to-end workflows (API, Stata, Python)
• docs/AGE_BANDS.md — standard 5-year age band codes for population indicators
• examples/ — runnable Python examples
• CHANGELOG.md — per-release change log
• doc/VERSIONING_POLICY.md — semver policy + component-level .ado version headers

Development

PYTHONIOENCODING=utf-8 python -m pytest tests/   # 62 cases across discovery, wb_text, wb_api_tools

Useful Makefile targets:

make wb-update-metadata   # refresh YAML cache (v0.1.0 pipeline)
make wb-metadata          # legacy YAML builder (pre-Phase-0)
make wb-metadata-csv      # legacy CSV builder
make wb-config            # batch data pulls from config.yaml

Branch model: feature work on develop; releases tag from main. See the v0.1.0 release notes for the full PR list.

Integration

The Python CLI and library plug into:

• Makefiles / pipelines (make wb-update-metadata, cron, GitHub Actions)
• Stata workflows (export CSV → import delimited, or use the Stata package directly)
• R workflows (readr::read_csv or arrow::read_parquet)
• Jupyter notebooks for ad-hoc analysis

License

See LICENSE.md. Developed to bridge Stata wbopendata workflows with modern Python pipelines for reproducible UNICEF / World Bank style analytics.