Owid Catalog

# /// script
# requires-python = ">=3.11"
# dependencies = ["owid-catalog"]
# ///

uv run --no-project script.py

pip install owid-catalog

# /// script
# requires-python = ">=3.11"
# dependencies = ["owid-catalog"]
# ///

from owid.catalog import fetch, search

# Fetch chart data by slug — returns a Table (a DataFrame with metadata)
tb = fetch("life-expectancy")
print(tb.head(30).to_csv())
print(tb.codebook.to_csv())

# Search charts, then fetch the top result
results = search("population")
print(results.to_frame().head(30).to_csv())
tb = results[0].fetch()

print(search("gdp per capita").to_frame().to_csv())  # search results
print(tb.head(30).to_csv())                          # data
print(tb.codebook.to_csv())                          # column, title, description, unit, source

from owid.catalog import fetch, search

tb = fetch("life-expectancy")
tb = fetch("https://ourworldindata.org/grapher/life-expectancy")

# Search charts (10 results by default; pass limit= for more)
results = search("child mortality", limit=30)
print(results.to_frame().to_csv())  # titles, descriptions, URLs
tb = results[0].fetch()

from owid.catalog import fetch, search

# Fuzzy, typo-tolerant matching on the table name (default)
results = search("population", kind="table")
print(results.to_frame().head(30).to_csv())

# Filter by data provider
results = search("wdi", kind="table", namespace="worldbank_wdi")

# Matching modes: "fuzzy" (default), "exact", "contains", "regex"
results = search("gdp.*capita", kind="table", match="regex")

# Keep only the latest version of each table
results = search("population", kind="table", latest=True)

# Fetch by catalog path: a whole table, or one indicator from it
tb = fetch("garden/un/2024-07-12/un_wpp/population")
tb = fetch("garden/un/2024-07-12/un_wpp/population#population")

from owid.catalog import Client, search

results = search("share of energy from renewable sources", kind="indicator", latest=True)
print(results.to_frame().head(30).to_csv())

# All fields: unit, score, n_charts, popularity, channel, namespace, ...
print(results.to_frame(all_fields=True).head(30).to_csv())

tb = results[0].fetch()        # the single indicator column
tb = results[0].fetch_table()  # the full table containing it

results = results.sort_by("n_charts", reverse=True)  # any result field
results = Client().indicators.search("CO2 emissions per capita", sort_by="similarity")

meta = tb["life_expectancy_0"].metadata
print(meta.unit, meta.short_unit, meta.description_short)
for origin in meta.origins:
    print(origin.producer, origin.attribution, origin.citation_full)

results = search("gdp", kind="table")

first = results[0]
for r in results[:5]:
    print(r.title)

filtered = results.filter(lambda r: "worldbank" in r.namespace)
sorted_results = results.sort_by("popularity", reverse=True)

# The single newest result (by version, or last_updated for charts) — not a filtered set
newest = results.latest()

df = results.to_frame()                  # DataFrame of the main fields
df = results.to_frame(all_fields=True)   # every field
records = results.to_dict()              # list of plain dicts

# In Jupyter, for human users only: switch the notebook display
results.set_ui_advanced()
results.set_ui_basic()  # default

# dependencies = ["owid-catalog", "owid-grapher-py"]
from owid.catalog import fetch
from owid.grapher import plot

tb = fetch("life-expectancy")
df = tb.reset_index()
chart = plot(df, x="years", entity="entities", y="life_expectancy_0", title="Life expectancy", types=["line", "map"])