fxmacrodata 1.0.0__tar.gz → 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. fxmacrodata-1.2.0/PKG-INFO +363 -0
  2. fxmacrodata-1.2.0/README.md +309 -0
  3. fxmacrodata-1.2.0/fxmacrodata/async_client.py +163 -0
  4. fxmacrodata-1.2.0/fxmacrodata/client.py +153 -0
  5. fxmacrodata-1.2.0/fxmacrodata/openbb/__init__.py +94 -0
  6. fxmacrodata-1.2.0/fxmacrodata/openbb/constants.py +120 -0
  7. fxmacrodata-1.2.0/fxmacrodata/openbb/launcher.py +58 -0
  8. fxmacrodata-1.2.0/fxmacrodata/openbb/metadata.py +352 -0
  9. fxmacrodata-1.2.0/fxmacrodata/openbb/models/__init__.py +0 -0
  10. fxmacrodata-1.2.0/fxmacrodata/openbb/models/commodities.py +105 -0
  11. fxmacrodata-1.2.0/fxmacrodata/openbb/models/cot.py +145 -0
  12. fxmacrodata-1.2.0/fxmacrodata/openbb/models/data_catalogue.py +143 -0
  13. fxmacrodata-1.2.0/fxmacrodata/openbb/models/forex.py +99 -0
  14. fxmacrodata-1.2.0/fxmacrodata/openbb/models/macro_indicators.py +112 -0
  15. fxmacrodata-1.2.0/fxmacrodata/openbb/models/release_calendar.py +94 -0
  16. fxmacrodata-1.2.0/fxmacrodata/openbb/router.py +109 -0
  17. fxmacrodata-1.2.0/fxmacrodata/openbb/utils/__init__.py +0 -0
  18. fxmacrodata-1.2.0/fxmacrodata/openbb/utils/catalogue.py +43 -0
  19. fxmacrodata-1.2.0/fxmacrodata/openbb/utils/helpers.py +135 -0
  20. fxmacrodata-1.2.0/fxmacrodata/openbb/workspace_backend.py +243 -0
  21. fxmacrodata-1.2.0/fxmacrodata.egg-info/PKG-INFO +363 -0
  22. fxmacrodata-1.2.0/fxmacrodata.egg-info/SOURCES.txt +37 -0
  23. fxmacrodata-1.2.0/fxmacrodata.egg-info/entry_points.txt +10 -0
  24. fxmacrodata-1.2.0/fxmacrodata.egg-info/requires.txt +44 -0
  25. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/pyproject.toml +47 -3
  26. fxmacrodata-1.2.0/tests/test_client.py +171 -0
  27. fxmacrodata-1.2.0/tests/test_client_auth.py +103 -0
  28. fxmacrodata-1.2.0/tests/test_openbb_helpers.py +99 -0
  29. fxmacrodata-1.2.0/tests/test_openbb_launchers.py +81 -0
  30. fxmacrodata-1.2.0/tests/test_openbb_metadata.py +58 -0
  31. fxmacrodata-1.2.0/tests/test_openbb_provider_fetchers.py +144 -0
  32. fxmacrodata-1.2.0/tests/test_openbb_workspace_backend.py +177 -0
  33. fxmacrodata-1.0.0/PKG-INFO +0 -172
  34. fxmacrodata-1.0.0/README.md +0 -143
  35. fxmacrodata-1.0.0/fxmacrodata/async_client.py +0 -83
  36. fxmacrodata-1.0.0/fxmacrodata/client.py +0 -75
  37. fxmacrodata-1.0.0/fxmacrodata.egg-info/PKG-INFO +0 -172
  38. fxmacrodata-1.0.0/fxmacrodata.egg-info/SOURCES.txt +0 -14
  39. fxmacrodata-1.0.0/fxmacrodata.egg-info/requires.txt +0 -14
  40. fxmacrodata-1.0.0/tests/test_client.py +0 -53
  41. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/LICENSE +0 -0
  42. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/fxmacrodata/__init__.py +0 -0
  43. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/fxmacrodata/exceptions.py +0 -0
  44. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/fxmacrodata/utils.py +0 -0
  45. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/fxmacrodata.egg-info/dependency_links.txt +0 -0
  46. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/fxmacrodata.egg-info/top_level.txt +0 -0
  47. {fxmacrodata-1.0.0 → fxmacrodata-1.2.0}/setup.cfg +0 -0
fxmacrodata-1.2.0/PKG-INFO ADDED
@@ -0,0 +1,363 @@
1
+ Metadata-Version: 2.4
2
+ Name: fxmacrodata
3
+ Version: 1.2.0
4
+ Summary: Python client for the FXMacroData API, providing forex macroeconomic data for traders, quants, and analysts.
5
+ Author-email: FXMacroData <info@fxmacrodata.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://fxmacrodata.com/?utm_source=pypi&utm_medium=package&utm_campaign=python_sdk
8
+ Project-URL: Documentation, https://fxmacrodata.com/api/docs?utm_source=pypi&utm_medium=package&utm_campaign=python_sdk
9
+ Project-URL: Source, https://github.com/fxmacrodata/fxmacrodata
10
+ Project-URL: Issues, https://github.com/fxmacrodata/fxmacrodata
11
+ Keywords: forex,macro data,macroeconomics,trading,quant,economic indicators,fxmacrodata,rapidapi
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: requests>=2.28
16
+ Requires-Dist: aiohttp>=3.8
17
+ Provides-Extra: openbb
18
+ Requires-Dist: openbb>=4.7.2; extra == "openbb"
19
+ Requires-Dist: openbb-core>=1.6.10; extra == "openbb"
20
+ Provides-Extra: openbb-api
21
+ Requires-Dist: openbb>=4.7.2; extra == "openbb-api"
22
+ Requires-Dist: openbb-core>=1.6.10; extra == "openbb-api"
23
+ Requires-Dist: openbb-platform-api>=1.3.6; extra == "openbb-api"
24
+ Provides-Extra: openbb-cli
25
+ Requires-Dist: openbb>=4.7.2; extra == "openbb-cli"
26
+ Requires-Dist: openbb-core>=1.6.10; extra == "openbb-cli"
27
+ Requires-Dist: openbb-cli>=1.0; extra == "openbb-cli"
28
+ Provides-Extra: mcp
29
+ Requires-Dist: openbb>=4.7.2; extra == "mcp"
30
+ Requires-Dist: openbb-core>=1.6.10; extra == "mcp"
31
+ Requires-Dist: openbb-mcp-server>=1.4.1; extra == "mcp"
32
+ Provides-Extra: workspace
33
+ Requires-Dist: fastapi>=0.100; extra == "workspace"
34
+ Requires-Dist: uvicorn>=0.23; extra == "workspace"
35
+ Provides-Extra: dev
36
+ Requires-Dist: fastapi>=0.100; extra == "dev"
37
+ Requires-Dist: httpx>=0.24; extra == "dev"
38
+ Requires-Dist: httpx2>=2.0; extra == "dev"
39
+ Requires-Dist: openbb-core>=1.6.10; extra == "dev"
40
+ Requires-Dist: openbb-platform-api>=1.3.6; extra == "dev"
41
+ Requires-Dist: pytest>=8.0; extra == "dev"
42
+ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
43
+ Requires-Dist: pytest-mock>=3.10; extra == "dev"
44
+ Requires-Dist: python-dotenv>=1.1; extra == "dev"
45
+ Requires-Dist: python-semantic-release>=7.23; extra == "dev"
46
+ Requires-Dist: twine>=4.0; extra == "dev"
47
+ Requires-Dist: build>=1.0; extra == "dev"
48
+ Requires-Dist: ruff>=0.0; extra == "dev"
49
+ Requires-Dist: mypy>=1.5; extra == "dev"
50
+ Requires-Dist: black>=24.0; extra == "dev"
51
+ Requires-Dist: types-requests>=2.28; extra == "dev"
52
+ Requires-Dist: uvicorn>=0.23; extra == "dev"
53
+ Dynamic: license-file
54
+
55
+ # FXMacroData Python SDK 🐍📊
56
+
57
+ ![PyPI Version](https://img.shields.io/pypi/v/fxmacrodata?color=blue&logo=python&style=flat-square)
58
+ ![Python Versions](https://img.shields.io/pypi/pyversions/fxmacrodata?style=flat-square)
59
+ ![License](https://img.shields.io/github/license/fxmacrodata/fxmacrodata?style=flat-square)
60
+ ![Build](https://img.shields.io/github/actions/workflow/status/fxmacrodata/fxmacrodata/ci-cd.yml?style=flat-square&logo=github)
61
+
62
+ 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=readme&utm_campaign=python_sdk).
63
+
64
+ It includes both synchronous and asynchronous clients and supports free USD macro endpoints.
65
+
66
+ ---
67
+
68
+ ## 🌟 Features
69
+
70
+ - Fetch:
71
+ - **Macroeconomic indicators** — policy rates, inflation, GDP, unemployment, bond yields, and 100+ more
72
+ - **FX spot rates** with optional technical indicators (SMA, RSI, MACD, Bollinger Bands)
73
+ - **Release calendars** — upcoming economic data release dates
74
+ - **Data catalogue** — discover available indicators per currency
75
+ - **COT data** — CFTC Commitment of Traders positioning
76
+ - **Commodity prices** — gold, silver, platinum
77
+ - Free access to **USD** macro data.
78
+ - FX spot-rate history through `get_fx_price`.
79
+ - API key required for protected datasets, including non-USD indicators, FX spot-rate history, COT, and commodities.
80
+ - Full support for:
81
+ - **Synchronous client**
82
+ - **Asynchronous client**
83
+ - Lightweight: depends only on `requests` and `aiohttp`.
84
+
85
+ ---
86
+
87
+ ## 📦 Installation
88
+
89
+ Install from PyPI:
90
+
91
+ ```bash
92
+ pip install fxmacrodata
93
+ ```
94
+
95
+ Or install the latest version from GitHub:
96
+
97
+ ```bash
98
+ pip install git+https://github.com/fxmacrodata/fxmacrodata.git
99
+ ```
100
+
101
+ ---
102
+
103
+ ## 🔧 Usage
104
+
105
+ ### Synchronous
106
+
107
+ ```python
108
+ from fxmacrodata import Client
109
+
110
+ client = Client(api_key="YOUR_API_KEY")
111
+
112
+ # Fetch macroeconomic indicators
113
+ data = client.get_indicator(
114
+ "aud", "policy_rate",
115
+ start_date="2023-01-01",
116
+ end_date="2023-11-01"
117
+ )
118
+ print(data)
119
+
120
+ # Forex price endpoint
121
+ fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
122
+ print(fx)
123
+
124
+ # Forex with technical indicators
125
+ fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
126
+ print(fx)
127
+
128
+ # Release calendar
129
+ calendar = client.get_calendar("usd")
130
+ print(calendar)
131
+
132
+ # Data catalogue — discover available indicators
133
+ catalogue = client.get_data_catalogue("usd")
134
+ print(catalogue)
135
+
136
+ # COT positioning data
137
+ cot = client.get_cot("eur", start_date="2025-01-01")
138
+ print(cot)
139
+
140
+ # Commodity prices
141
+ gold = client.get_commodities("gold", start_date="2026-01-01")
142
+ print(gold)
143
+ ```
144
+
145
+ ---
146
+
147
+ ### Asynchronous
148
+
149
+ ```python
150
+ import asyncio
151
+ from fxmacrodata import AsyncClient
152
+
153
+ async def main():
154
+ async with AsyncClient(api_key="YOUR_API_KEY") as client:
155
+ # Fetch macroeconomic indicators
156
+ data = await client.get_indicator("eur", "inflation")
157
+ print(data)
158
+
159
+ # Forex price endpoint
160
+ fx = await client.get_fx_price("usd", "jpy")
161
+ print(fx)
162
+
163
+ # Release calendar
164
+ calendar = await client.get_calendar("usd")
165
+ print(calendar)
166
+
167
+ # Data catalogue
168
+ catalogue = await client.get_data_catalogue("usd")
169
+ print(catalogue)
170
+
171
+ # COT positioning
172
+ cot = await client.get_cot("jpy")
173
+ print(cot)
174
+
175
+ # Commodity prices
176
+ gold = await client.get_commodities("gold")
177
+ print(gold)
178
+
179
+ asyncio.run(main())
180
+ ```
181
+
182
+ ---
183
+
184
+ ## OpenBB Integration
185
+
186
+ FXMacroData supports all practical OpenBB integration paths from this package:
187
+
188
+ - OpenBB Python: installable provider/router extension for `obb.fxmacrodata.*`.
189
+ - OpenBB REST API: `/api/v1/fxmacrodata/*` routes through `openbb-api`.
190
+ - OpenBB Workspace, generated: widgets generated by `openbb-api` from inline metadata.
191
+ - OpenBB Workspace, custom: standalone backend serving `widgets.json`, `apps.json`, and data endpoints.
192
+ - OpenBB MCP: tools exposed through `openbb-mcp`.
193
+ - OpenBB CLI: commands available after `openbb-build`.
194
+
195
+ OpenBB packages require Python 3.10+. Install the OpenBB Python extra:
196
+
197
+ ```bash
198
+ pip install "fxmacrodata[openbb]"
199
+ openbb-build
200
+ ```
201
+
202
+ Then use FXMacroData from the OpenBB Python interface:
203
+
204
+ ```python
205
+ from openbb import obb
206
+
207
+ obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"
208
+
209
+ catalogue = obb.fxmacrodata.data_catalogue(
210
+ currency="USD",
211
+ provider="fxmacrodata",
212
+ ).to_df()
213
+
214
+ inflation = obb.fxmacrodata.macro_indicators(
215
+ currency="USD",
216
+ indicator="inflation",
217
+ start_date="2020-01-01",
218
+ provider="fxmacrodata",
219
+ ).to_df()
220
+
221
+ eurusd = obb.fxmacrodata.fx_historical(
222
+ base="EUR",
223
+ quote="USD",
224
+ start_date="2024-01-01",
225
+ provider="fxmacrodata",
226
+ ).to_df()
227
+ ```
228
+
229
+ Run the OpenBB REST API and generated Workspace backend:
230
+
231
+ ```bash
232
+ pip install "fxmacrodata[openbb-api]"
233
+ openbb-build
234
+ fxmacrodata-openbb-api --host 127.0.0.1 --port 6900
235
+ ```
236
+
237
+ Workspace can be connected to `http://127.0.0.1:6900`. The generated
238
+ `/widgets.json` uses FXMacroData's inline OpenBB widget metadata.
239
+
240
+ Run the OpenBB Workspace custom backend:
241
+
242
+ ```bash
243
+ pip install "fxmacrodata[workspace]"
244
+ fxmacrodata-openbb-backend
245
+ ```
246
+
247
+ Default backend URL:
248
+
249
+ ```text
250
+ http://127.0.0.1:7779
251
+ ```
252
+
253
+ Workspace exposes `/widgets.json`, `/apps.json`, `/catalogue`,
254
+ `/release_calendar`, `/macro_indicator`, `/forex`, `/cot`, and `/commodity`.
255
+ Swagger/OpenAPI docs are disabled by default for this backend. For local
256
+ debugging only, set `FXMACRODATA_OPENBB_ENABLE_DOCS=1` before starting it.
257
+
258
+ Run OpenBB MCP:
259
+
260
+ ```bash
261
+ pip install "fxmacrodata[mcp]"
262
+ openbb-build
263
+ fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001
264
+ ```
265
+
266
+ Run OpenBB CLI:
267
+
268
+ ```bash
269
+ pip install "fxmacrodata[openbb-cli]"
270
+ openbb-build
271
+ openbb
272
+ ```
273
+
274
+ See `docs/openbb-integration.md` for the full integration matrix and the
275
+ separate upstream OpenBB repository contribution path.
276
+
277
+ ---
278
+
279
+ ## 📘 API Overview
280
+
281
+ ### `get_indicator(currency, indicator, start_date=None, end_date=None)`
282
+ Fetches macroeconomic indicator time series data.
283
+
284
+ - `currency`: `"usd"`, `"aud"`, `"eur"`, `"gbp"`, `"cad"`, `"nok"`, `"nzd"`, `"jpy"`, `"brl"`, `"cny"`, `"dkk"`, `"pln"`, `"sek"`, `"sgd"`, etc.
285
+ - `indicator`: `"policy_rate"`, `"inflation"`, `"gdp"`, `"unemployment"`, `"trade_balance"`, `"current_account_balance"`, `"gov_bond_10y"`, etc.
286
+ - **API key required for non-USD.**
287
+
288
+ ### `get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)`
289
+ Fetches daily FX spot rates between two currencies.
290
+
291
+ - `indicators`: Optional comma-separated technical indicators — `"sma_20"`, `"sma_50"`, `"sma_200"`, `"rsi_14"`, `"macd"`, `"ema_12"`, `"ema_26"`, `"bollinger_bands"`, or `"all"`.
292
+ - **API key required.**
293
+
294
+ ### `get_calendar(currency, indicator=None)`
295
+ Fetches upcoming economic data release dates for a currency.
296
+
297
+ - `indicator`: Optional filter to a specific indicator slug.
298
+ - Returns `announcement_datetime` (Unix timestamp) and `release` (indicator slug).
299
+
300
+ ### `get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)`
301
+ Discovers available macroeconomic indicators for a given currency.
302
+
303
+ - Returns a dict keyed by indicator slug with `name`, `unit`, `frequency`, and `has_official_forecast`.
304
+ - **API key required for non-USD.**
305
+
306
+ ### `get_cot(currency, start_date=None, end_date=None)`
307
+ Fetches CFTC Commitment of Traders (COT) positioning data.
308
+
309
+ - Supported currencies: `AUD`, `CAD`, `CHF`, `EUR`, `GBP`, `JPY`, `NZD`, `USD`.
310
+ - **API key required for non-USD.**
311
+
312
+ ### `get_commodities(indicator, start_date=None, end_date=None)`
313
+ Fetches commodity price time series.
314
+
315
+ - `indicator`: `"gold"`, `"silver"`, or `"platinum"`.
316
+ - **API key required.**
317
+
318
+ ---
319
+
320
+ ## 💹 Supported Currencies & Indicators
321
+
322
+ **18 currencies supported:** USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, HKD, SGD, NOK, PLN, SEK, DKK, BRL, CNY, KRW, MXN.
323
+
324
+ 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.
325
+
326
+ | Category | Metric | USD | EUR | AUD | GBP |
327
+ |---------|--------|-----|-----|-----|-----|
328
+ | **Economy** | GDP Growth | ✓ | ✓ | ✓ | ✓ |
329
+ | | Inflation Rate | ✓ | ✓ | ✓ | ✓ |
330
+ | | Trade Balance | ✓ | ✓ | ✓ | ✓ |
331
+ | | Current Account Balance | ✓ | ✓ | ✓ | ✓ |
332
+ | | Retail Sales | ✓ | ✓ | ✓ | ✓ |
333
+ | | Industrial Production | ✓ | — | — | — |
334
+ | **Labor Market** | Unemployment Rate | ✓ | ✓ | ✓ | ✓ |
335
+ | | Employment Level | ✓ | ✓ | ✓ | ✓ |
336
+ | | Full-Time Employment | ✓ | ✓ | ✓ | — |
337
+ | | Part-Time Employment | ✓ | ✓ | ✓ | ✓ |
338
+ | | Participation Rate | ✓ | ✓ | ✓ | ✓ |
339
+ | | Non-Farm Payrolls | ✓ | — | — | — |
340
+ | **Monetary Policy** | Policy Rate | ✓ | ✓ | ✓ | ✓ |
341
+ | | Risk-Free Rate | ✓ | ✓ | ✓ | ✓ |
342
+ | | Central Bank Assets | ✓ | — | ✓ | — |
343
+ | **Government Bond Yields** | 2-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
344
+ | | 5-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
345
+ | | 10-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
346
+ | | Inflation-Linked Bond | ✓ | ✓ | ✓ | ✓ |
347
+
348
+ ---
349
+
350
+ ## 📄 License
351
+
352
+ MIT License © FXMacroData
353
+
354
+ ---
355
+
356
+ ## 🌐 Links
357
+
358
+ - Website: https://fxmacrodata.com
359
+ - API Docs: https://fxmacrodata.com/docs
360
+ - GitHub: https://github.com/fxmacrodata/fxmacrodata
361
+ - PyPI: https://pypi.org/project/fxmacrodata/
362
+ - Readthedocs: https://fxmacrodata.readthedocs.io/en/latest/
363
+ - Zenodo: https://zenodo.org/records/18280968
fxmacrodata-1.2.0/README.md ADDED
@@ -0,0 +1,309 @@
1
+ # FXMacroData Python SDK 🐍📊
2
+
3
+ ![PyPI Version](https://img.shields.io/pypi/v/fxmacrodata?color=blue&logo=python&style=flat-square)
4
+ ![Python Versions](https://img.shields.io/pypi/pyversions/fxmacrodata?style=flat-square)
5
+ ![License](https://img.shields.io/github/license/fxmacrodata/fxmacrodata?style=flat-square)
6
+ ![Build](https://img.shields.io/github/actions/workflow/status/fxmacrodata/fxmacrodata/ci-cd.yml?style=flat-square&logo=github)
7
+
8
+ 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=readme&utm_campaign=python_sdk).
9
+
10
+ It includes both synchronous and asynchronous clients and supports free USD macro endpoints.
11
+
12
+ ---
13
+
14
+ ## 🌟 Features
15
+
16
+ - Fetch:
17
+ - **Macroeconomic indicators** — policy rates, inflation, GDP, unemployment, bond yields, and 100+ more
18
+ - **FX spot rates** with optional technical indicators (SMA, RSI, MACD, Bollinger Bands)
19
+ - **Release calendars** — upcoming economic data release dates
20
+ - **Data catalogue** — discover available indicators per currency
21
+ - **COT data** — CFTC Commitment of Traders positioning
22
+ - **Commodity prices** — gold, silver, platinum
23
+ - Free access to **USD** macro data.
24
+ - FX spot-rate history through `get_fx_price`.
25
+ - API key required for protected datasets, including non-USD indicators, FX spot-rate history, COT, and commodities.
26
+ - Full support for:
27
+ - **Synchronous client**
28
+ - **Asynchronous client**
29
+ - Lightweight: depends only on `requests` and `aiohttp`.
30
+
31
+ ---
32
+
33
+ ## 📦 Installation
34
+
35
+ Install from PyPI:
36
+
37
+ ```bash
38
+ pip install fxmacrodata
39
+ ```
40
+
41
+ Or install the latest version from GitHub:
42
+
43
+ ```bash
44
+ pip install git+https://github.com/fxmacrodata/fxmacrodata.git
45
+ ```
46
+
47
+ ---
48
+
49
+ ## 🔧 Usage
50
+
51
+ ### Synchronous
52
+
53
+ ```python
54
+ from fxmacrodata import Client
55
+
56
+ client = Client(api_key="YOUR_API_KEY")
57
+
58
+ # Fetch macroeconomic indicators
59
+ data = client.get_indicator(
60
+ "aud", "policy_rate",
61
+ start_date="2023-01-01",
62
+ end_date="2023-11-01"
63
+ )
64
+ print(data)
65
+
66
+ # Forex price endpoint
67
+ fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
68
+ print(fx)
69
+
70
+ # Forex with technical indicators
71
+ fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
72
+ print(fx)
73
+
74
+ # Release calendar
75
+ calendar = client.get_calendar("usd")
76
+ print(calendar)
77
+
78
+ # Data catalogue — discover available indicators
79
+ catalogue = client.get_data_catalogue("usd")
80
+ print(catalogue)
81
+
82
+ # COT positioning data
83
+ cot = client.get_cot("eur", start_date="2025-01-01")
84
+ print(cot)
85
+
86
+ # Commodity prices
87
+ gold = client.get_commodities("gold", start_date="2026-01-01")
88
+ print(gold)
89
+ ```
90
+
91
+ ---
92
+
93
+ ### Asynchronous
94
+
95
+ ```python
96
+ import asyncio
97
+ from fxmacrodata import AsyncClient
98
+
99
+ async def main():
100
+ async with AsyncClient(api_key="YOUR_API_KEY") as client:
101
+ # Fetch macroeconomic indicators
102
+ data = await client.get_indicator("eur", "inflation")
103
+ print(data)
104
+
105
+ # Forex price endpoint
106
+ fx = await client.get_fx_price("usd", "jpy")
107
+ print(fx)
108
+
109
+ # Release calendar
110
+ calendar = await client.get_calendar("usd")
111
+ print(calendar)
112
+
113
+ # Data catalogue
114
+ catalogue = await client.get_data_catalogue("usd")
115
+ print(catalogue)
116
+
117
+ # COT positioning
118
+ cot = await client.get_cot("jpy")
119
+ print(cot)
120
+
121
+ # Commodity prices
122
+ gold = await client.get_commodities("gold")
123
+ print(gold)
124
+
125
+ asyncio.run(main())
126
+ ```
127
+
128
+ ---
129
+
130
+ ## OpenBB Integration
131
+
132
+ FXMacroData supports all practical OpenBB integration paths from this package:
133
+
134
+ - OpenBB Python: installable provider/router extension for `obb.fxmacrodata.*`.
135
+ - OpenBB REST API: `/api/v1/fxmacrodata/*` routes through `openbb-api`.
136
+ - OpenBB Workspace, generated: widgets generated by `openbb-api` from inline metadata.
137
+ - OpenBB Workspace, custom: standalone backend serving `widgets.json`, `apps.json`, and data endpoints.
138
+ - OpenBB MCP: tools exposed through `openbb-mcp`.
139
+ - OpenBB CLI: commands available after `openbb-build`.
140
+
141
+ OpenBB packages require Python 3.10+. Install the OpenBB Python extra:
142
+
143
+ ```bash
144
+ pip install "fxmacrodata[openbb]"
145
+ openbb-build
146
+ ```
147
+
148
+ Then use FXMacroData from the OpenBB Python interface:
149
+
150
+ ```python
151
+ from openbb import obb
152
+
153
+ obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"
154
+
155
+ catalogue = obb.fxmacrodata.data_catalogue(
156
+ currency="USD",
157
+ provider="fxmacrodata",
158
+ ).to_df()
159
+
160
+ inflation = obb.fxmacrodata.macro_indicators(
161
+ currency="USD",
162
+ indicator="inflation",
163
+ start_date="2020-01-01",
164
+ provider="fxmacrodata",
165
+ ).to_df()
166
+
167
+ eurusd = obb.fxmacrodata.fx_historical(
168
+ base="EUR",
169
+ quote="USD",
170
+ start_date="2024-01-01",
171
+ provider="fxmacrodata",
172
+ ).to_df()
173
+ ```
174
+
175
+ Run the OpenBB REST API and generated Workspace backend:
176
+
177
+ ```bash
178
+ pip install "fxmacrodata[openbb-api]"
179
+ openbb-build
180
+ fxmacrodata-openbb-api --host 127.0.0.1 --port 6900
181
+ ```
182
+
183
+ Workspace can be connected to `http://127.0.0.1:6900`. The generated
184
+ `/widgets.json` uses FXMacroData's inline OpenBB widget metadata.
185
+
186
+ Run the OpenBB Workspace custom backend:
187
+
188
+ ```bash
189
+ pip install "fxmacrodata[workspace]"
190
+ fxmacrodata-openbb-backend
191
+ ```
192
+
193
+ Default backend URL:
194
+
195
+ ```text
196
+ http://127.0.0.1:7779
197
+ ```
198
+
199
+ Workspace exposes `/widgets.json`, `/apps.json`, `/catalogue`,
200
+ `/release_calendar`, `/macro_indicator`, `/forex`, `/cot`, and `/commodity`.
201
+ Swagger/OpenAPI docs are disabled by default for this backend. For local
202
+ debugging only, set `FXMACRODATA_OPENBB_ENABLE_DOCS=1` before starting it.
203
+
204
+ Run OpenBB MCP:
205
+
206
+ ```bash
207
+ pip install "fxmacrodata[mcp]"
208
+ openbb-build
209
+ fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001
210
+ ```
211
+
212
+ Run OpenBB CLI:
213
+
214
+ ```bash
215
+ pip install "fxmacrodata[openbb-cli]"
216
+ openbb-build
217
+ openbb
218
+ ```
219
+
220
+ See `docs/openbb-integration.md` for the full integration matrix and the
221
+ separate upstream OpenBB repository contribution path.
222
+
223
+ ---
224
+
225
+ ## 📘 API Overview
226
+
227
+ ### `get_indicator(currency, indicator, start_date=None, end_date=None)`
228
+ Fetches macroeconomic indicator time series data.
229
+
230
+ - `currency`: `"usd"`, `"aud"`, `"eur"`, `"gbp"`, `"cad"`, `"nok"`, `"nzd"`, `"jpy"`, `"brl"`, `"cny"`, `"dkk"`, `"pln"`, `"sek"`, `"sgd"`, etc.
231
+ - `indicator`: `"policy_rate"`, `"inflation"`, `"gdp"`, `"unemployment"`, `"trade_balance"`, `"current_account_balance"`, `"gov_bond_10y"`, etc.
232
+ - **API key required for non-USD.**
233
+
234
+ ### `get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)`
235
+ Fetches daily FX spot rates between two currencies.
236
+
237
+ - `indicators`: Optional comma-separated technical indicators — `"sma_20"`, `"sma_50"`, `"sma_200"`, `"rsi_14"`, `"macd"`, `"ema_12"`, `"ema_26"`, `"bollinger_bands"`, or `"all"`.
238
+ - **API key required.**
239
+
240
+ ### `get_calendar(currency, indicator=None)`
241
+ Fetches upcoming economic data release dates for a currency.
242
+
243
+ - `indicator`: Optional filter to a specific indicator slug.
244
+ - Returns `announcement_datetime` (Unix timestamp) and `release` (indicator slug).
245
+
246
+ ### `get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)`
247
+ Discovers available macroeconomic indicators for a given currency.
248
+
249
+ - Returns a dict keyed by indicator slug with `name`, `unit`, `frequency`, and `has_official_forecast`.
250
+ - **API key required for non-USD.**
251
+
252
+ ### `get_cot(currency, start_date=None, end_date=None)`
253
+ Fetches CFTC Commitment of Traders (COT) positioning data.
254
+
255
+ - Supported currencies: `AUD`, `CAD`, `CHF`, `EUR`, `GBP`, `JPY`, `NZD`, `USD`.
256
+ - **API key required for non-USD.**
257
+
258
+ ### `get_commodities(indicator, start_date=None, end_date=None)`
259
+ Fetches commodity price time series.
260
+
261
+ - `indicator`: `"gold"`, `"silver"`, or `"platinum"`.
262
+ - **API key required.**
263
+
264
+ ---
265
+
266
+ ## 💹 Supported Currencies & Indicators
267
+
268
+ **18 currencies supported:** USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, HKD, SGD, NOK, PLN, SEK, DKK, BRL, CNY, KRW, MXN.
269
+
270
+ 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.
271
+
272
+ | Category | Metric | USD | EUR | AUD | GBP |
273
+ |---------|--------|-----|-----|-----|-----|
274
+ | **Economy** | GDP Growth | ✓ | ✓ | ✓ | ✓ |
275
+ | | Inflation Rate | ✓ | ✓ | ✓ | ✓ |
276
+ | | Trade Balance | ✓ | ✓ | ✓ | ✓ |
277
+ | | Current Account Balance | ✓ | ✓ | ✓ | ✓ |
278
+ | | Retail Sales | ✓ | ✓ | ✓ | ✓ |
279
+ | | Industrial Production | ✓ | — | — | — |
280
+ | **Labor Market** | Unemployment Rate | ✓ | ✓ | ✓ | ✓ |
281
+ | | Employment Level | ✓ | ✓ | ✓ | ✓ |
282
+ | | Full-Time Employment | ✓ | ✓ | ✓ | — |
283
+ | | Part-Time Employment | ✓ | ✓ | ✓ | ✓ |
284
+ | | Participation Rate | ✓ | ✓ | ✓ | ✓ |
285
+ | | Non-Farm Payrolls | ✓ | — | — | — |
286
+ | **Monetary Policy** | Policy Rate | ✓ | ✓ | ✓ | ✓ |
287
+ | | Risk-Free Rate | ✓ | ✓ | ✓ | ✓ |
288
+ | | Central Bank Assets | ✓ | — | ✓ | — |
289
+ | **Government Bond Yields** | 2-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
290
+ | | 5-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
291
+ | | 10-Year Govt Bond | ✓ | ✓ | ✓ | ✓ |
292
+ | | Inflation-Linked Bond | ✓ | ✓ | ✓ | ✓ |
293
+
294
+ ---
295
+
296
+ ## 📄 License
297
+
298
+ MIT License © FXMacroData
299
+
300
+ ---
301
+
302
+ ## 🌐 Links
303
+
304
+ - Website: https://fxmacrodata.com
305
+ - API Docs: https://fxmacrodata.com/docs
306
+ - GitHub: https://github.com/fxmacrodata/fxmacrodata
307
+ - PyPI: https://pypi.org/project/fxmacrodata/
308
+ - Readthedocs: https://fxmacrodata.readthedocs.io/en/latest/
309
+ - Zenodo: https://zenodo.org/records/18280968