Catalog Library¶

The owid-catalog library is the foundation of Our World in Data's data management system. It serves two main purposes:

Data API: Access OWID data through unified client interfaces. We provide a reference for the most important objects and methods.
Data Structures: Enhanced pandas DataFrames with rich metadata support

AI/LLM integration

An llms.txt file is available for AI agents and LLM tools.

Installation¶

pip install owid-catalog

Quick Start¶

Accessing Data via API¶

from owid.catalog import Client

client = Client()

# Get chart data
tb = client.charts.fetch("life-expectancy")

# Search for indicators
results = client.indicators.search("renewable energy")
variable = results[0].fetch()

# Query catalog tables
results = client.tables.search(table="population", namespace="un")
tb = results[0].fetch()

Working with Data Structures¶

from owid.catalog import Table

# Tables are pandas DataFrames with metadata
tb = Table(df)
tb.metadata.short_name = "population"

# Metadata propagates through operations
tb_filtered = tb[tb["year"] > 2000]  # Keeps metadata
tb_grouped = tb.groupby("country").sum()  # Preserves metadata