Metadata-Version: 2.4
Name: bceaoapi
Version: 0.1.1
Summary: Python client for BCEAO/UEMOA macroeconomic data
License: MIT
Project-URL: Homepage, https://github.com/beethogedeon/bceaoapi
Project-URL: Documentation, https://github.com/beethogedeon/bceaoapi#readme
Project-URL: Repository, https://github.com/beethogedeon/bceaoapi
Project-URL: Bug Tracker, https://github.com/beethogedeon/bceaoapi/issues
Keywords: BCEAO,UEMOA,WAEMU,West Africa,economics,macroeconomics,finance,open data,time series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: requests>=2.28
Provides-Extra: etl
Requires-Dist: openpyxl>=3.1; extra == "etl"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn[standard]>=0.27; extra == "api"
Provides-Extra: all
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn[standard]>=0.27; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# bceaoapi

**BCEAO/UEMOA macroeconomic data** in Python. No setup required.

```bash
pip install bceaoapi
```

```python
from bceaoapi import BCEAO

b = BCEAO()  # connects to the public API automatically

# Senegal GDP in 2022
b.get_value("IMECO", "PIB nominal", "SENEGAL", 2022)
# → 17330.12

# Full time series
gdp = b.get_series_by("IMECO", "PIB nominal", "SENEGAL", start="2000")
gdp.plot(title="Senegal GDP (bn FCFA)")

# All 8 countries in one call
inflation = b.get_cross_country("IHPC", "Ensemble", start="2015")
inflation.plot(title="UEMOA Inflation")
```

---

## Coverage

| | |
|--|--|
| **Datasets** | 39 (GDP, inflation, exchange rates, banking, balance of payments, public debt…) |
| **Series** | 9 500+ — one per country/indicator combination |
| **Observations** | 830 000+ — from 1960 to 2025 |
| **Countries** | BENIN · BURKINA FASO · CÔTE D'IVOIRE · GUINÉE BISSAU · MALI · NIGER · SÉNÉGAL · TOGO |

---

## Exploring available data

No series codes needed. Discover data in 3 steps:

```python
# 1. What datasets are available?
b.list_datasets()

# 2. What indicators are in a dataset?
b.list_indicators("IHPC")
# ['Alimentation', 'Ameublement', 'Ensemble', 'Transport', ...]

# 3. Fetch
b.get_series_by("IHPC", "Ensemble", "BURKINA FASO", start="2010")
```

Or search by free text:

```python
b.search("taux de change", frequency="MONTHLY")
b.search("PIB", country="MALI")
```

---

## Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `list_datasets()` | `DataFrame` | All available datasets |
| `list_countries(dataset?)` | `list` | Available countries |
| `list_indicators(dataset)` | `list` | Indicators in a dataset |
| `get_series_by(dataset, indicator, country)` | `Series` | Time series by name |
| `get_value(dataset, indicator, country, year)` | `float` | Single data point |
| `get_cross_country(dataset, indicator)` | `DataFrame` | All 8 countries side by side |
| `get_dataset(dataset, country?)` | `DataFrame` | All indicators in a dataset |
| `get_series(code)` | `Series` | Series by code (e.g. `KKKSR1012A0BP`) |
| `search(query)` | `DataFrame` | Free-text search |

`start` / `end` parameters accept a year (`"2000"`) or an ISO date (`"2000-01-31"`).

---

## Error handling

```python
from bceaoapi import AmbiguousQueryError, SeriesNotFoundError

try:
    b.get_series_by("PIBN", "PIB", "SENEGAL")
except AmbiguousQueryError as e:
    print(e)
    # 2 series match. Use a more specific label.
    # Found: [KKKSR1012A0BP] PIB marchand, [KKKSR1013A0BP] PIB non marchand

try:
    b.get_series_by("IHPC", "xxx", "MALI")
except SeriesNotFoundError as e:
    print(e)
    # Tip: use b.list_indicators('IHPC') to see available labels.
```

---

## Data source

Data published by the [BCEAO](https://www.bceao.int) via [edenpub.bceao.int](https://www.edenpub.bceao.int/rapport.php).
This package is independent and not affiliated with or endorsed by the BCEAO.

## License

MIT
