Metadata-Version: 2.4
Name: fxmacrodata
Version: 1.2.2
Summary: Python client for the FXMacroData API, providing forex macroeconomic data for traders, quants, and analysts.
Author-email: FXMacroData <info@fxmacrodata.com>
License-Expression: MIT
Project-URL: Homepage, https://fxmacrodata.com/?utm_source=pypi&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=homepage
Project-URL: Documentation, https://fxmacrodata.com/api/docs?utm_source=pypi&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=docs
Project-URL: Source, https://github.com/fxmacrodata/fxmacrodata
Project-URL: Issues, https://github.com/fxmacrodata/fxmacrodata
Keywords: forex,macro data,macroeconomics,trading,quant,economic indicators,fxmacrodata,rapidapi
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: aiohttp>=3.8
Provides-Extra: openbb
Requires-Dist: openbb>=4.7.2; extra == "openbb"
Requires-Dist: openbb-core>=1.6.10; extra == "openbb"
Provides-Extra: openbb-api
Requires-Dist: openbb>=4.7.2; extra == "openbb-api"
Requires-Dist: openbb-core>=1.6.10; extra == "openbb-api"
Requires-Dist: openbb-platform-api>=1.3.6; extra == "openbb-api"
Provides-Extra: openbb-cli
Requires-Dist: openbb>=4.7.2; extra == "openbb-cli"
Requires-Dist: openbb-core>=1.6.10; extra == "openbb-cli"
Requires-Dist: openbb-cli>=1.0; extra == "openbb-cli"
Provides-Extra: mcp
Requires-Dist: openbb>=4.7.2; extra == "mcp"
Requires-Dist: openbb-core>=1.6.10; extra == "mcp"
Requires-Dist: openbb-mcp-server>=1.4.1; extra == "mcp"
Provides-Extra: workspace
Requires-Dist: fastapi>=0.100; extra == "workspace"
Requires-Dist: uvicorn>=0.23; extra == "workspace"
Provides-Extra: dev
Requires-Dist: fastapi>=0.100; extra == "dev"
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: httpx2>=2.0; extra == "dev"
Requires-Dist: openbb-core>=1.6.10; extra == "dev"
Requires-Dist: openbb-platform-api>=1.3.6; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: python-dotenv>=1.1; extra == "dev"
Requires-Dist: python-semantic-release>=7.23; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: ruff==0.15.22; extra == "dev"
Requires-Dist: mypy==2.3.1; extra == "dev"
Requires-Dist: black==26.5.1; extra == "dev"
Requires-Dist: types-requests>=2.28; extra == "dev"
Requires-Dist: uvicorn>=0.23; extra == "dev"
Dynamic: license-file

# FXMacroData Python SDK 🐍📊

![PyPI Version](https://img.shields.io/pypi/v/fxmacrodata?color=blue&logo=python&style=flat-square)
![Python Versions](https://img.shields.io/pypi/pyversions/fxmacrodata?style=flat-square)
![License](https://img.shields.io/github/license/fxmacrodata/fxmacrodata?style=flat-square)
![Build](https://img.shields.io/github/actions/workflow/status/fxmacrodata/fxmacrodata/ci-cd.yml?style=flat-square&logo=github)

The **FXMacroData Python SDK** provides a simple and efficient interface for fetching **macroeconomic indicators**, **forex prices**, **release calendars**, **COT positioning**, and **commodity prices** from [FXMacroData](https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme).  

Use synchronous and asynchronous clients to bring the data into research notebooks, backtests and applications.

[Subscribe to FXMacroData](https://fxmacrodata.com/subscribe?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=subscribe) for non-USD data, full available history, FX, commodities and positioning. Use the public USD workflow to evaluate the integration before connecting your subscription.

---

## 🌟 Features

- Fetch:
  - **Macroeconomic indicators** — policy rates, inflation, GDP, unemployment, bond yields, and more: 97 distinct indicators across 656 endpoints
  - **FX spot rates** with optional technical indicators (SMA, RSI, MACD, Bollinger Bands)
  - **Release calendars** — upcoming economic data release dates
  - **Data catalogue** — discover available indicators per currency
  - **COT data** — CFTC Commitment of Traders positioning
  - **Commodity prices** — gold, silver, platinum
- Evaluate with public **USD** macro data covering the most recent 90 days; connect your FXMacroData subscription for full available history.
- FX spot-rate history through `get_fx_price`.
- A key from an authorized FXMacroData subscription is required for protected datasets, including non-USD indicators, FX spot-rate history, COT, and commodities.
- Full support for:
  - **Synchronous client**
  - **Asynchronous client**
- Lightweight: depends only on `requests` and `aiohttp`.

---

## 📦 Installation

Install from PyPI:

```bash
pip install fxmacrodata
```

Or install the latest version from GitHub:

```bash
pip install git+https://github.com/fxmacrodata/fxmacrodata.git
```

---

## 🔧 Usage

### Synchronous

```python
from fxmacrodata import Client

client = Client(api_key="YOUR_API_KEY")

# Fetch macroeconomic indicators
data = client.get_indicator(
    "aud", "policy_rate",
    start_date="2023-01-01",
    end_date="2023-11-01"
)
print(data)

# Forex price endpoint
fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
print(fx)

# Forex with technical indicators
fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
print(fx)

# Release calendar
calendar = client.get_calendar("usd")
print(calendar)

# Data catalogue — discover available indicators
catalogue = client.get_data_catalogue("usd")
print(catalogue)

# COT positioning data
cot = client.get_cot("eur", start_date="2025-01-01")
print(cot)

# Commodity prices
gold = client.get_commodities("gold", start_date="2026-01-01")
print(gold)
```

---

### Asynchronous

```python
import asyncio
from fxmacrodata import AsyncClient

async def main():
    async with AsyncClient(api_key="YOUR_API_KEY") as client:
        # Fetch macroeconomic indicators
        data = await client.get_indicator("eur", "inflation")
        print(data)

        # Forex price endpoint
        fx = await client.get_fx_price("usd", "jpy")
        print(fx)

        # Release calendar
        calendar = await client.get_calendar("usd")
        print(calendar)

        # Data catalogue
        catalogue = await client.get_data_catalogue("usd")
        print(catalogue)

        # COT positioning
        cot = await client.get_cot("jpy")
        print(cot)

        # Commodity prices
        gold = await client.get_commodities("gold")
        print(gold)

asyncio.run(main())
```

### Timeouts and errors

Every request has a 30-second timeout by default. Change it per client:

```python
Client(api_key="YOUR_API_KEY", timeout=60)            # seconds
Client(api_key="YOUR_API_KEY", timeout=(3.05, 120))   # (connect, read)
AsyncClient(api_key="YOUR_API_KEY", timeout=60)       # total seconds
```

All errors are `FXMacroDataError` or one of its subclasses:

| Exception | Raised when |
| --- | --- |
| `FXMacroDataAPIError` | The API returns a non-200 status (`.status_code` is set). |
| `FXMacroDataResponseError` | The API returns 200 but the body is an error message or not a JSON object. |
| `FXMacroDataTimeoutError` | The request exceeds the timeout. |
| `FXMacroDataTransportError` | The connection fails (DNS, TLS, network). |
| `FXMacroDataRedirectError` | A redirect would send your API key to a different origin, so it is refused. |

Your API key is never included in error messages, and it is only sent over
HTTPS to the origin you configured: redirects to another host or to plain HTTP
are refused rather than followed with the key attached.

---

## OpenBB Integration

FXMacroData supports all practical OpenBB integration paths from this package:

- OpenBB Python: installable provider/router extension for `obb.fxmacrodata.*`.
- OpenBB REST API: `/api/v1/fxmacrodata/*` routes through `openbb-api`.
- OpenBB Workspace, generated: widgets generated by `openbb-api` from inline metadata.
- OpenBB Workspace, custom: standalone backend serving `widgets.json`, `apps.json`, and data endpoints.
- OpenBB MCP: tools exposed through `openbb-mcp`.
- OpenBB CLI: commands available after `openbb-build`.

OpenBB packages require Python 3.10+. Install the OpenBB Python extra:

```bash
pip install "fxmacrodata[openbb]"
openbb-build
```

Then use FXMacroData from the OpenBB Python interface:

```python
from openbb import obb

obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"

catalogue = obb.fxmacrodata.data_catalogue(
    currency="USD",
    provider="fxmacrodata",
).to_df()

inflation = obb.fxmacrodata.macro_indicators(
    currency="USD",
    indicator="inflation",
    start_date="2020-01-01",
    provider="fxmacrodata",
).to_df()

eurusd = obb.fxmacrodata.fx_historical(
    base="EUR",
    quote="USD",
    start_date="2024-01-01",
    provider="fxmacrodata",
).to_df()
```

Run the OpenBB REST API and generated Workspace backend:

```bash
pip install "fxmacrodata[openbb-api]"
openbb-build
fxmacrodata-openbb-api --host 127.0.0.1 --port 6900
```

Workspace can be connected to `http://127.0.0.1:6900`. The generated
`/widgets.json` uses FXMacroData's inline OpenBB widget metadata.

Run the OpenBB Workspace custom backend:

```bash
pip install "fxmacrodata[workspace]"
fxmacrodata-openbb-backend
```

Default backend URL:

```text
http://127.0.0.1:7779
```

Workspace exposes `/widgets.json`, `/apps.json`, `/catalogue`,
`/release_calendar`, `/macro_indicator`, `/forex`, `/cot`, and `/commodity`.
Swagger/OpenAPI docs are disabled by default for this backend. For local
debugging only, set `FXMACRODATA_OPENBB_ENABLE_DOCS=1` before starting it.

Run OpenBB MCP:

```bash
pip install "fxmacrodata[mcp]"
openbb-build
fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001
```

Run OpenBB CLI:

```bash
pip install "fxmacrodata[openbb-cli]"
openbb-build
openbb
```

See `docs/openbb-integration.md` for the full integration matrix and the
separate upstream OpenBB repository contribution path.

---

## 📘 API Overview

### `get_indicator(currency, indicator, start_date=None, end_date=None)`
Fetches macroeconomic indicator time series data.

- `currency`: `"usd"`, `"aud"`, `"eur"`, `"gbp"`, `"cad"`, `"nok"`, `"nzd"`, `"jpy"`, `"brl"`, `"cny"`, `"dkk"`, `"pln"`, `"sek"`, `"sgd"`, etc.
- `indicator`: `"policy_rate"`, `"inflation"`, `"gdp"`, `"unemployment"`, `"trade_balance"`, `"current_account_balance"`, `"gov_bond_10y"`, etc.
- **API key required for non-USD.**

### `get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)`
Fetches daily FX spot rates between two currencies.

- `indicators`: Optional comma-separated technical indicators — `"sma_20"`, `"sma_50"`, `"sma_200"`, `"rsi_14"`, `"macd"`, `"ema_12"`, `"ema_26"`, `"bollinger_bands"`, or `"all"`.
- **API key required.**

### `get_calendar(currency, indicator=None)`
Fetches upcoming economic data release dates for a currency.

- `indicator`: Optional filter to a specific indicator slug.
- Returns `announcement_datetime` (Unix timestamp) and `release` (indicator slug).

### `get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)`
Discovers available macroeconomic indicators for a given currency.

- Returns a dict keyed by indicator slug with `name`, `unit`, `frequency`, and `has_official_forecast`.
- **API key required for non-USD.**

### `get_cot(currency, start_date=None, end_date=None)`
Fetches CFTC Commitment of Traders (COT) positioning data.

- Supported currencies: `AUD`, `CAD`, `CHF`, `EUR`, `GBP`, `JPY`, `NZD`, `USD`.
- **API key required for non-USD.**

### `get_commodities(indicator, start_date=None, end_date=None)`
Fetches commodity price time series.

- `indicator`: `"gold"`, `"silver"`, or `"platinum"`.
- **API key required.**

---

## 💹 Supported Currencies & Indicators

**18 currencies supported:** AUD, BRL, CAD, CHF, CNH, CNY, DKK, EUR, GBP, ILS, JPY, NGN, NOK, NZD, PEN, SEK, THB, USD.

The table below shows a sample of indicator coverage across four major currencies. Use `get_data_catalogue()` to discover the full list for any currency.

| Category | Metric | USD | EUR | AUD | GBP |
|---------|--------|-----|-----|-----|-----|
| **Economy** | GDP Growth | ✓ | ✓ | ✓ | ✓ |
|  | Inflation Rate | ✓ | ✓ | ✓ | ✓ |
|  | Trade Balance | ✓ | ✓ | ✓ | ✓ |
|  | Current Account Balance | ✓ | ✓ | ✓ | ✓ |
|  | Retail Sales | ✓ | ✓ | ✓ | ✓ |
|  | Industrial Production | ✓ | — | — | — |
| **Labor Market** | Unemployment Rate | ✓ | ✓ | ✓ | ✓ |
|  | Employment Level | ✓ | ✓ | ✓ | ✓ |
|  | Full-Time Employment | ✓ | ✓ | ✓ | — |
|  | Part-Time Employment | ✓ | ✓ | ✓ | ✓ |
|  | Participation Rate | ✓ | ✓ | ✓ | ✓ |
|  | Non-Farm Payrolls | ✓ | — | — | — |
| **Monetary Policy** | Policy Rate | ✓ | ✓ | ✓ | ✓ |
|  | Risk-Free Rate | ✓ | ✓ | ✓ | ✓ |
|  | Central Bank Assets | ✓ | — | ✓ | — |
| **Government Bond Yields** | 2-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
|  | 5-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
|  | 10-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
|  | Inflation-Linked Bond | ✓ | ✓ | ✓ | ✓ |

---

## 📄 License

MIT License © FXMacroData

---

## 🌐 Links

- Website: https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
- API Docs: https://fxmacrodata.com/docs?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
- GitHub: https://github.com/fxmacrodata/fxmacrodata
- PyPI: https://pypi.org/project/fxmacrodata/
- Readthedocs: https://fxmacrodata.readthedocs.io/en/latest/
- Zenodo: https://zenodo.org/records/18280968
