# owid-grapher-py

> A Python library for creating interactive Our World in Data charts in Jupyter notebooks. Provides a declarative API inspired by Altair for building visualizations that render using OWID's Grapher JavaScript library.

Key features:
- Create line charts, bar charts, scatter plots, slope charts, and world maps
- Fluent method-chaining API similar to Altair/Vega-Lite
- Renders interactive charts directly in Jupyter notebooks
- Fetch and visualize data from live OWID charts
- Export charts to PNG, SVG, or standalone HTML

## Documentation

- [README](https://github.com/owid/owid-grapher-py/blob/master/README.md): Installation, quick start, API reference for plot() and Chart class
- [Documentation Index](https://github.com/owid/owid-grapher-py/blob/master/docs/index.md): Overview and links to detailed documentation

## API Reference

- [owid.grapher](https://github.com/owid/owid-grapher-py/blob/master/docs/api-reference/grapher.md): Core Chart class, plot() function, and configuration dataclasses
- [owid.grapher.notebook](https://github.com/owid/owid-grapher-py/blob/master/docs/api-reference/notebook.md): Tools for auto-generating notebooks from existing charts
- [owid.site](https://github.com/owid/owid-grapher-py/blob/master/docs/api-reference/site.md): Functions to fetch chart configs and data from ourworldindata.org

## Examples

- [Quickstart Notebook](https://github.com/owid/owid-grapher-py/blob/master/examples/quickstart.ipynb): Comprehensive walkthrough with basic examples
- [Top Charts (Simple API)](https://github.com/owid/owid-grapher-py/blob/master/examples/top_charts_2025_simple.ipynb): Real OWID chart replications using plot()
- [Top Charts (Full API)](https://github.com/owid/owid-grapher-py/blob/master/examples/top_charts_2025.ipynb): Advanced examples using Chart class with method chaining

## Development

- [Development Guide](https://github.com/owid/owid-grapher-py/blob/master/docs/dev/README.md): Setup, testing, and contributing
- [CLAUDE.md](https://github.com/owid/owid-grapher-py/blob/master/CLAUDE.md): Architecture overview and development patterns

## Optional

- [PyPI Package](https://pypi.org/project/owid-grapher-py/): Package installation and version history
- [GitHub Issues](https://github.com/owid/owid-grapher-py/issues): Bug reports and feature requests
- [Our World in Data](https://ourworldindata.org): Source of chart designs and data
