owid

name	owid
description	Fetch data and charts from Our World in Data — search for charts/pages, download CSV datasets, retrieve metadata and chart configurations, and get filtered data by country and time range. Use this skill when the user wants global development data (GDP, CO2, life expectancy, population, etc.) or asks about data-driven topics like climate, health, poverty, energy, or education, even if they don't mention Our World in Data by name.
compatibility	jq required for owid-indicators TSV output
allowed-tools	bash

Our World in Data (OWID)

Access data from Our World in Data's public APIs. Three scripts, three APIs:

Script	API	Purpose
scripts/owid-search	Search API	Find charts and pages by keyword
scripts/owid-data	Grapher Chart API	Download chart data as CSV, metadata, etc.
scripts/owid-indicators	Indicators + Semantic Search	Find and fetch raw indicator data by ID

All data is CC BY 4.0 licensed.

Choosing the right approach

• Don't know the slug or indicator ID? Start with owid-search "query" (charts) or owid-indicators --search "query" (indicators).
• Want a specific chart's data as CSV? Use owid-data <slug>.
• Want raw variable data with entity/time filtering? Use owid-indicators <id>. This is the most powerful approach — semantic search finds the indicator, then you get TSV (requires jq) or JSON with entity names, years, and values.

owid-indicators

Semantic search for indicators and direct data fetching. This is the most flexible data access method.

Search

owid-indicators --search "<query>" [--limit N] [--min-popularity 0.5]

Returns raw JSON with query, total_results, and results array (indicator_id, title, snippet, score, n_charts, catalog_path). Use --min-popularity to filter out low-relevance indicators (0-1 scale).

Fetch data

owid-indicators <id>                           # full TSV: entity, year, value (requires jq)
owid-indicators <id> --entity NAME             # filter by entity (case-insensitive substring)
owid-indicators <id> --time 2000..2020          # filter by year range
owid-indicators <id> --time latest              # latest value per entity
owid-indicators <id> --entity France --time 2000..2020  # combined filters
owid-indicators <id> -f metadata                # indicator metadata (name, unit, timespan, dimensions)
owid-indicators <id> -f json                    # raw data.json

APIs used

Endpoint	Used for
https://search.owid.io/indicators?q=...	Semantic search
https://api.ourworldindata.org/v1/indicators/{id}.data.json	Data values
https://api.ourworldindata.org/v1/indicators/{id}.metadata.json	Metadata

Semantic search result fields

Field	Description
indicator_id	Numeric ID — use with data/metadata fetch
title	Indicator name
snippet	Description snippet
score	Semantic relevance 0-1
n_charts	Number of charts using this indicator
catalog_path	Internal dataset path

owid-search

owid-search <query> [options]

Option	Description
--type charts | pages	Content type (default: charts)
--page N	Page number, 0-indexed (default: 0)
--hits N	Results per page, 1-100 (default: 20)
--countries u~CN	Countries separated by ~ (charts only)
--topics TOPIC	Topic filter (charts only)
--require-all	Only charts containing ALL countries

Output is raw JSON with query, nbHits, results array (title, slug, url, type, variantName).

Available topics: tags database.

Each chart result includes: title, slug, subtitle, variantName, availableEntities, availableTabs, url.

owid-data

owid-data <slug>[.format] [options]

Option	Description
-f, --format FMT	csv, metadata, config, readme, zip, values, png, svg (default: csv)
-o, --out PATH	Save output to file (required for png/svg)
--csv-type full | filtered	full = all data, filtered = chart subset (default: full)
--country ENTITY	Filter by entity. ~OWID_WRL for World. (repeatable)
--time RANGE	year, 2000..2020, latest, earliest
--tab TAB	Active tab: table, map, chart, line, scatter, stacked-area, discrete-bar, stacked-discrete-bar, slope, stacked-bar, marimekko
--short-names	Compact column names (no spaces)

Image options (--format png|svg)

Option	Description
--im-type TYPE	Preset: twitter, og, thumbnail, square, uncaptioned
--im-width N	Width in pixels
--im-height N	Height in pixels
--im-minimal	Minimal mode (no title/source line)
--im-font-size N	Font size
--im-square-size N	Size for square images

Format details

Format	Returns
csv	Time series data (Entity, Code, Year/Day, data columns)
metadata	Chart title, subtitle, citation, column metadata
config	Raw grapher configuration (dimensions, axes, colors)
readme	Markdown README describing the dataset
zip	ZIP containing csv + metadata.json + readme.md
values	JSON data values filtered by entity/time
png	Chart as PNG image (requires -o path)
svg	Chart as SVG image (requires -o path)

Metadata fields (columns in .metadata.json)

Each column object includes: titleShort, titleLong, descriptionShort, descriptionKey, shortUnit, unit, timespan, type, owidVariableId, shortName, citationShort, citationLong. The owidVariableId can be used directly with owid-indicators.

Workflows

Find and fetch indicator data (recommended)

1. owid-indicators --search "wine consumption"     → find indicator IDs
2. owid-indicators 1203983 --entity France --time 2000..2020  → filtered TSV

Find and download chart data

1. owid-search "co2 emissions per capita"          → find chart slugs
2. owid-data co2-emissions -f metadata              → inspect metadata (units, owidVariableId)
3. owid-data co2-emissions --country USA --time 2000..2020  → filtered CSV

Explore by topic

owid-search "emissions" --topics "Energy" --hits 5

Export chart image for notes

owid-data life-expectancy -f png --country France --time 2000..2020 -o ~/secondbrain/assets/life-expectancy-france.png
owid-data co2-emissions -f svg --tab map --time latest -o ~/secondbrain/assets/co2-map.svg

Gotchas

• Chart slugs are exact — always search first to confirm the slug before fetching data.
• Indicator IDs are numeric — use owid-indicators --search to find them, then pass the ID.
• Country names use full names — United States not USA. Use ~ (tilde) to separate multiple countries in the chart/search APIs.
• Entities in indicators use a different ID system. Always use --entity with the indicator script; it resolves names to IDs automatically via metadata.
• Time ranges use .. — 2000..2020, latest, earliest, or a single year 2020.
• CSV column names default to long human-readable names. Use --short-names for machine-readable headers.
• filtered csvType returns only visible chart data (selected entities and time range). full returns everything.
• 403 on certain datasets — some charts have non-redistributable data. The API returns 403. Use search to find alternative charts.
• --tab only affects values, png, and svg — the CSV endpoint ignores the tab parameter.
• Image export requires -o PATH — png/svg are binary; always specify an output file.
• Popularity filter is aggressive — --min-popularity 0.9 may return zero results. Start with 0.5 and adjust.
• Indicators API returns parallel arrays — values, years, entities are zipped by index. The script handles this automatically.