Metadata-Version: 2.4
Name: africaMarketsAnalytics
Version: 0.3.0
Summary: Python SDK for the Africa Markets Analytics API — African stock market data (BRVM + 15 exchanges) with a simple, ergonomic API.
Author: Africa Markets Analytics
License: MIT
Project-URL: Homepage, https://africamarkets.easyit4finance.com
Project-URL: Documentation, https://africamarkets.easyit4finance.com/api-docs
Project-URL: Dashboard, https://africamarkets.easyit4finance.com/dashboard
Keywords: finance,stocks,africa,brvm,jse,market-data,ohlcv
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Provides-Extra: pandas
Requires-Dist: pandas>=1.3; extra == "pandas"
Dynamic: license-file

# africaMarketsAnalytics

Python SDK for the **Africa Markets Analytics** API — daily OHLCV, technical
indicators, signals, backtests and recommendations for **African stock markets**
(BRVM/WAEMU + 15 national exchanges: Morocco, Nigeria, South Africa, Egypt,
Ghana, Kenya, Tunisia, Mauritius…). A simple, ergonomic Python API.

## Install

```bash
pip install africaMarketsAnalytics      # core
pip install "africaMarketsAnalytics[pandas]"   # + pandas for DataFrames
```

## API key required

An API key is **required for every call** (no anonymous access). Create one from
your dashboard, then pass it via `ama.set_key(...)` or the `AMA_API_KEY`
environment variable: 👉 https://africamarkets.easyit4finance.com/dashboard

```python
import africaMarketsAnalytics as ama
ama.set_key("brvm_live_xxxxxxxx")     # required (or export AMA_API_KEY)
```

| | **Free key** | **Paid key (Pro / Premium / Enterprise)** |
|---|---|---|
| Endpoints | `tickers`, `markets`, `usage` only | all endpoints |
| Markets | BRVM / WAEMU | BRVM + 15 national exchanges |
| OHLCV, indicators, signals | — | ✅ |
| `advice()` / `backtest()` | — | ✅ (advice: Pro+, backtest: Premium+) |
| History | 1 year | 5 years (Pro) / 10 years (Premium) / full (Enterprise) |
| Daily quota | 50 | 100 → 100,000 |

Each developer uses **their own key** (sent as the `X-API-Key` header).

## Quickstart

```python
import africaMarketsAnalytics as ama
ama.set_key("brvm_live_xxxxxxxx")

# One ticker — OHLCV history as a pandas DataFrame (index = Date)
t = ama.Ticker("SNTS")
df = t.history(period="1y")          # 5d,1mo,3mo,6mo,1y,2y,3y,5y,10y,ytd,max
print(df.tail())

# Metadata
t.info            # {symbol, nom, secteur, pays, dateMin, dateMax, nBars}

# Technical indicators -> DataFrame
t.rsi(period=14)
t.macd(fast=12, slow=26, signal=9)
t.indicator("bollinger", period=20, mult=2)

# Signals, backtest, recommendation
t.signals("macd")
t.backtest(strategy="rsi")
t.advice()

# The whole listed universe
ama.tickers()                        # DataFrame

# Bulk download (multi-symbol, MultiIndex columns)
data = ama.download(["SNTS", "NPN"], period="5y")

# Market-wide endpoints
ama.market(); ama.indices(); ama.news(); ama.usage()

# Dividends (BRVM) -> DataFrame
ama.dividends()                      # all issuers
ama.dividends("SNTS")                # one issuer

# Bonds (BRVM, Premium key) -> DataFrame
ama.bonds()                          # all bonds
ama.bonds(actif="true", maturite_min=2027)   # filter: active, maturity >= 2027
```

## Date range

`history()` accepts either a `period` or explicit `start`/`end` (`YYYY-MM-DD`):

```python
t.history(start="2024-01-01", end="2024-12-31")
```

History depth is capped by your plan (Free: 12 months, Pro: 5 years,
Enterprise: full history).

## Errors

| Exception | When |
|-----------|------|
| `ama.AuthError` | missing/invalid/revoked key (401/403) |
| `ama.NotFound` | unknown ticker / endpoint (404) |
| `ama.RateLimited` | daily quota exceeded (429) |
| `ama.AMAError` | base class for all SDK errors |

## Low-level client

```python
from africaMarketsAnalytics import Client
c = Client(api_key="brvm_live_…", base_url="https://africamarkets.easyit4finance.com")
c.get("/ohlcv", {"symbol": "SNTS", "from": "2024-01-01"})
```

---
© Africa Markets Analytics · API docs: https://africamarkets.easyit4finance.com/api-docs
