financecalendar 0.1.8__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. financecalendar-0.1.8/.gitignore +6 -0
  2. financecalendar-0.1.8/LICENSE +21 -0
  3. financecalendar-0.1.8/PKG-INFO +458 -0
  4. financecalendar-0.1.8/README.md +425 -0
  5. financecalendar-0.1.8/pyproject.toml +50 -0
  6. financecalendar-0.1.8/src/financecalendar/__init__.py +17 -0
  7. financecalendar-0.1.8/src/financecalendar/cli.py +502 -0
  8. financecalendar-0.1.8/src/financecalendar/client.py +546 -0
  9. financecalendar-0.1.8/src/financecalendar/py.typed +0 -0
  10. financecalendar-0.1.8/tests/conftest.py +125 -0
  11. financecalendar-0.1.8/tests/fixtures/calendar.json +258 -0
  12. financecalendar-0.1.8/tests/fixtures/calendar_csv.txt +8 -0
  13. financecalendar-0.1.8/tests/fixtures/calendar_high.json +320 -0
  14. financecalendar-0.1.8/tests/fixtures/calendar_holidays.json +463 -0
  15. financecalendar-0.1.8/tests/fixtures/calendar_tz.json +266 -0
  16. financecalendar-0.1.8/tests/fixtures/changes.json +919 -0
  17. financecalendar-0.1.8/tests/fixtures/countries.json +101 -0
  18. financecalendar-0.1.8/tests/fixtures/crypto.json +105 -0
  19. financecalendar-0.1.8/tests/fixtures/error_429.json +16 -0
  20. financecalendar-0.1.8/tests/fixtures/error_bad_tz.json +11 -0
  21. financecalendar-0.1.8/tests/fixtures/error_next_404.json +11 -0
  22. financecalendar-0.1.8/tests/fixtures/error_series_404.json +11 -0
  23. financecalendar-0.1.8/tests/fixtures/error_unknown_series.json +11 -0
  24. financecalendar-0.1.8/tests/fixtures/history_us_cpi.json +137 -0
  25. financecalendar-0.1.8/tests/fixtures/holidays_lse_2027.json +72 -0
  26. financecalendar-0.1.8/tests/fixtures/holidays_nyse.json +148 -0
  27. financecalendar-0.1.8/tests/fixtures/market_status_lse.json +34 -0
  28. financecalendar-0.1.8/tests/fixtures/market_status_nyse.json +34 -0
  29. financecalendar-0.1.8/tests/fixtures/next_cpi_uk.json +47 -0
  30. financecalendar-0.1.8/tests/fixtures/next_fomc.json +47 -0
  31. financecalendar-0.1.8/tests/fixtures/next_fomc_tz.json +48 -0
  32. financecalendar-0.1.8/tests/fixtures/openapi.json +8191 -0
  33. financecalendar-0.1.8/tests/fixtures/series.json +603 -0
  34. financecalendar-0.1.8/tests/fixtures/series_detail_fomc.json +916 -0
  35. financecalendar-0.1.8/tests/fixtures/status.json +23 -0
  36. financecalendar-0.1.8/tests/fixtures/today.json +115 -0
  37. financecalendar-0.1.8/tests/fixtures/week.json +259 -0
  38. financecalendar-0.1.8/tests/fixtures/week_next.json +410 -0
  39. financecalendar-0.1.8/tests/test_archive.py +50 -0
  40. financecalendar-0.1.8/tests/test_archive_cli.py +85 -0
  41. financecalendar-0.1.8/tests/test_cli.py +225 -0
  42. financecalendar-0.1.8/tests/test_client.py +272 -0
  43. financecalendar-0.1.8/tests/test_crypto.py +145 -0
  44. financecalendar-0.1.8/tests/test_enrichment_api.py +183 -0
  45. financecalendar-0.1.8/tests/test_observations.py +72 -0
  46. financecalendar-0.1.8/tests/test_quality_api.py +78 -0
  47. financecalendar-0.1.8/tests/test_vintage_archive.py +127 -0
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ dist/
3
+ build/
4
+ *.egg-info/
5
+ __pycache__/
6
+ .pytest_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Awareness Days Ltd (financecalendar.com)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,458 @@
1
+ Metadata-Version: 2.5
2
+ Name: financecalendar
3
+ Version: 0.1.8
4
+ Summary: Economic calendar Python client and CLI. Starter adds forecasts/results and tools; ongoing Free Developer schedule JSON is available. Account key required.
5
+ Project-URL: Homepage, https://www.financecalendar.com/api/
6
+ Project-URL: Documentation, https://www.financecalendar.com/api/
7
+ Project-URL: Changelog, https://www.financecalendar.com/api/changelog/
8
+ Project-URL: Source, https://github.com/awarenessdays/financecalendar-api/tree/main/clients/python
9
+ Project-URL: Issues, https://github.com/awarenessdays/financecalendar-api/issues
10
+ Author: Awareness Days Ltd (financecalendar.com)
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: central-banks,cpi,economic-calendar,finance,fomc,market-holidays,nfp
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Financial and Insurance Industry
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Office/Business :: Financial
24
+ Requires-Python: >=3.10
25
+ Requires-Dist: httpx>=0.27
26
+ Requires-Dist: tzdata; platform_system == 'Windows'
27
+ Provides-Extra: pandas
28
+ Requires-Dist: pandas>=2.0; extra == 'pandas'
29
+ Provides-Extra: test
30
+ Requires-Dist: build>=1.2; extra == 'test'
31
+ Requires-Dist: pytest>=8; extra == 'test'
32
+ Description-Content-Type: text/markdown
33
+
34
+ # financecalendar
35
+
36
+ Bring economic-release dates, consensus forecasts and published results into Python, pandas and terminal workflows with the [financecalendar.com API](https://www.financecalendar.com/api/). Paid plans support release forecasts for 60 mapped headline measures across 10 economies. Available values appear in each event’s `forecasts` field, refreshed hourly and labelled with their update time and source count. Coverage varies by release; the mapped total is not the number with a live forecast at any moment. Provider consensus now spans **12 selected US headline release series**, with source-linked actual/prior values for covered records. The same API also supplies central bank decisions, exchange holidays and source-backed crypto events. Use each record’s metric, reference period and source evidence when comparing expectations with results.
37
+
38
+ [Paid API plans](https://www.financecalendar.com/pricing/) include annually billed Starter (**1,000 requests/UTC day and 25,000/UTC calendar month**). Build is **US$9.99/month or US$95.90/year** for **100,000/day**. Scale is **US$29/month or US$278.40/year** for **1,000,000/day** and the complete current dataset download. [Inspect the public sample](https://www.financecalendar.com/api/sample/) before choosing a plan. Check the [current Starter quote](https://www.financecalendar.com/pricing/#starter) or the [machine-readable offer](https://www.financecalendar.com/wp-json/fc/v1/product-offer).
39
+
40
+ [Free Developer](https://www.financecalendar.com/account/?free=1) is ongoing schedule JSON access: **100 successful responses per UTC calendar month, at most 10 per UTC day**, one verified account and one API key issued after approval (allow up to 48 hours for review), no card or automatic charge. Use `GET /calendar` or `/today` for economic-release and central-bank schedules from UTC today through the following six days, with up to 20 records and no pagination. Country (up to three codes) and impact filters are supported; `from` and `to` may narrow, but cannot extend, the seven-date UTC window. Free `/today` is the current UTC date’s schedule, without market-status or holiday payloads. Free responses omit forecasts, consensus, actual/prior figures and numerical evidence, and mark releases that have them (`figures_available`, `result_available`); Starter adds release forecasts across 10 economies, these recorded fields, wider dates/history, formats, hosted MCP and browser tools.
41
+
42
+ The [public calendar remains free to browse](https://www.financecalendar.com/events/). Hosted MCP, status and the wider data examples below require a paid plan. The public sample, product offer and OpenAPI document can be read directly without a key; SDK requests consistently use your configured account key. Set `FC_API_KEY` securely or pass `Client(api_key=...)`. Missing credentials fail before any network request.
43
+
44
+ Starter is billed annually and includes **1,000 requests per UTC day and 25,000 per UTC calendar month**. Build includes **100,000 requests per day** and Scale **1,000,000 per day**. All account keys share the applicable allowance. Daily usage resets at 00:00 UTC; monthly usage resets at 00:00 UTC on the first day of the next calendar month. Existing paid customers retain their contracted prices and applicable allowances; check your account or `/keys/me` for effective limits. See [current plans](https://www.financecalendar.com/pricing/) for billing options and complete snapshot downloads.
45
+
46
+ Free Developer counts successful committed HTTP 200 JSON schedule responses, including valid empty responses. Invalid or denied requests, quota errors and pre-commit server failures do not consume its allowance. Usage is shared by the account and survives key rotation; daily and monthly resets follow UTC. Already-enrolled evaluations retain their original 25-successful-request budget, 48-hour clock from first use and original scope. New trial enrolment is closed. Existing paid, legacy and custom access grants are preserved; no account is silently converted to Free Developer.
47
+
48
+ For paid plans, daily and monthly quota usage counts admitted requests, not successful responses. Requests refused with HTTP 429 do not consume more allowance; a request that passes the quota check can still consume allowance if it later returns an error. Retained per-key request history remains a separate attempt diagnostic and can include rejected requests.
49
+
50
+ ```sh
51
+ export FC_API_KEY='fc_live_YOUR_ACTUAL_KEY'
52
+ ```
53
+
54
+ Use your real key and keep it private; never include it in a shared notebook or URL.
55
+
56
+ ## Install the Python client
57
+
58
+ Requires Python 3.10 or newer. To install the [PyPI release](https://pypi.org/project/financecalendar/) when available, use a virtual environment:
59
+
60
+ ```sh
61
+ python -m pip install financecalendar
62
+ financecalendar --help
63
+ ```
64
+
65
+ For the optional pandas helpers, install `"financecalendar[pandas]"`.
66
+ For a version-pinned download of the earlier beta, see the
67
+ [GitHub archives and checksums](https://github.com/awarenessdays/financecalendar-api/releases/tag/clients-annual-restored-2026-11-15).
68
+
69
+ ## Install from source
70
+
71
+ To build directly from the public source repository:
72
+
73
+ ```sh
74
+ git clone https://github.com/awarenessdays/financecalendar-api.git
75
+ cd financecalendar-api/clients/python
76
+ python -m venv .venv
77
+ .venv/bin/python -m pip install .
78
+ .venv/bin/financecalendar --help
79
+ ```
80
+
81
+ Use `.venv\Scripts\python` and `.venv\Scripts\financecalendar` on Windows.
82
+ Install `".[pandas]"` instead of `.` for the optional DataFrame helper.
83
+
84
+ The runtime dependencies are `httpx` and, on Windows, `tzdata` for time zone names.
85
+
86
+ ## Quick start
87
+
88
+ A first bounded request within free access:
89
+
90
+ ```python
91
+ from financecalendar import Client
92
+
93
+ with Client() as fc: # reads your private FC_API_KEY
94
+ sample = fc.calendar(limit=10)
95
+ print(sample["events"])
96
+ ```
97
+
98
+ The following `/next` example and the wider methods below require a paid plan:
99
+
100
+ ```python
101
+ from financecalendar import Client
102
+
103
+ fc = Client() # requires FC_API_KEY; reads FC_API_BASE if set
104
+ nxt = fc.next("fomc")["next"]
105
+ print(nxt["date"], nxt["time_et"], nxt["consensus"], nxt["url"])
106
+
107
+ week = fc.week(country="us", impact="high", tz="Europe/London")
108
+ for e in week["events"]:
109
+ print(e["date"], e["time_local"], e["name"], e["consensus"])
110
+ ```
111
+
112
+ Every method returns the API's JSON as plain dicts and lists.
113
+
114
+ Paid event responses include nullable `period` and `release_stage` fields. Human CLI output
115
+ shows these details when provided, labels unknown economic release times
116
+ `time unknown`, and retains `all day` for exchange holidays.
117
+
118
+ | Method | Endpoint |
119
+ |---|---|
120
+ | `calendar(**params)` | `GET /calendar` (from_, to, country, impact, category, asset, series, include_holidays, status, tz, limit, offset) |
121
+ | `crypto_calendar(asset=None, **params)` | `GET /calendar` with `category=crypto` forced; canonical asset IDs |
122
+ | `calendar_csv(**params)` | `GET /calendar?format=csv`, returns the CSV text |
123
+ | `iter_calendar(from_, to, **params)` | yields every event over any span: pages with offset/limit and splits ranges longer than 92 days |
124
+ | `today(country=None, tz=None)` | `GET /today` |
125
+ | `week(which="this", **params)` | `GET /week` |
126
+ | `next(series, country=None, tz=None)` | `GET /next` |
127
+ | `series(**params)` | `GET /series` |
128
+ | `series_detail(code, tz=None)` | `GET /series/{code}` |
129
+ | `history(series, **params)` | `GET /history` |
130
+ | `enrichment_history(series, **params)` | `GET /enrichment/history`; evidenced results with from_, to, limit, offset, ledger_cursor and publication_revision |
131
+ | `enrichment_editions(event_id, **params)` | `GET /enrichment/editions`; accepted editions with limit, offset and both pagination pins |
132
+ | `holidays(exchange="nyse", year=None)` | `GET /holidays` |
133
+ | `market_status(exchange="nyse")` | `GET /market-status` |
134
+ | `changes(since=None, **params)` | One page from `GET /changes`; accepts series, change, limit and cursor |
135
+ | `countries()` | `GET /countries` |
136
+ | `status()` | `GET /status` |
137
+ | `quality(**params)` | `GET /quality`, the current snapshot's quality and evidence-coverage report |
138
+ | `observations(**params)` | One page from `GET /observations`; accepts series, event_id, role, reference_period, limit, offset and snapshot_generated_at |
139
+ | `openapi()` | `GET /openapi` |
140
+
141
+ ### Economic results and editions
142
+
143
+ ```python
144
+ with Client() as fc:
145
+ results = fc.enrichment_history("us-adp", from_="2026-01-01", limit=20)
146
+ for release in results["releases"]:
147
+ print(release["actual"], release["consensus"], release["selected_editions"])
148
+ editions = fc.enrichment_editions(release["event_id"], limit=100)
149
+ ```
150
+
151
+ These endpoints cover `us-jolts`, `us-adp`, `us-ism-services` and
152
+ `us-trade-balance` when the enrichment service is enabled and accepted evidence
153
+ is available. First pages return `ledger_cursor` and `publication_revision`.
154
+ Follow `next_offset` with the same filters and both pins; they are required
155
+ when offset is above zero. The ledger pin excludes later appends, while the
156
+ publication pin prevents combining different published views. On HTTP 409,
157
+ restart at offset zero without the old pins.
158
+ Values retain exact decimal strings, nulls, reference periods and provenance.
159
+ `available_at` describes recorded source availability; `received_at` records
160
+ Finance Calendar's receipt. A provider archive is labelled separately from an
161
+ engine capture. `as_of_supported` is false; these responses do not reconstruct
162
+ an original first print. Normal account authentication and quota rules apply.
163
+
164
+ ### Long ranges and paging
165
+
166
+ ```python
167
+ from datetime import date
168
+
169
+ rows = list(fc.iter_calendar(date(2026, 1, 1), date(2026, 12, 31), country="us,gb", impact="high"))
170
+ ```
171
+
172
+ For changes, follow `next_cursor` until `has_more` is false, passing that cursor
173
+ alone to `fc.changes(cursor=...)`. Advance the `since` checkpoint only after all
174
+ pages finish. HTTP 409 means the snapshot changed: restart with the original
175
+ `since` and filters and deduplicate repeated changes. Reload the full snapshot
176
+ if the checkpoint is outside the 30-day retention window. The CLI accepts the
177
+ same continuation with `financecalendar changes --cursor ...`.
178
+
179
+ ### Errors
180
+
181
+ Any 4xx or 5xx raises `FinanceCalendarError` with the API's message:
182
+
183
+ ```python
184
+ from financecalendar import Client, FinanceCalendarError
185
+
186
+ try:
187
+ Client().calendar(tz="Mars/Olympus")
188
+ except FinanceCalendarError as exc:
189
+ print(exc.status, exc.message, exc.retry_after) # 400, "tz must be an IANA timezone...", None
190
+ ```
191
+
192
+ On a 429 the `retry_after` attribute holds the `Retry-After` seconds.
193
+
194
+ ### pandas
195
+
196
+ ```python
197
+ from financecalendar import Client, to_dataframe
198
+
199
+ df = to_dataframe(Client().history("us-cpi", limit=24))
200
+ print(df[["date", "consensus", "actual"]])
201
+ ```
202
+
203
+ `to_dataframe` accepts a list of event rows or a whole calendar/history response and parses `date` and `release_at_utc` to datetimes. pandas is imported only when you call it.
204
+
205
+ ### Configuration
206
+
207
+ | Setting | Constructor | Environment variable |
208
+ |---|---|---|
209
+ | Base URL | `Client(base_url=...)` | `FC_API_BASE` (default `https://www.financecalendar.com/wp-json/fc/v1`; an edge mirror at `https://api.financecalendar.com/v1` is planned) |
210
+ | API key | `Client(api_key=...)` | `FC_API_KEY`, sent as `X-API-Key` |
211
+ | Timeout | `Client(timeout=20)` | |
212
+
213
+ `Client` is also a context manager and has `close()`.
214
+
215
+ ## Crypto coverage
216
+
217
+ ```python
218
+ from financecalendar import Client, to_dataframe
219
+
220
+ with Client() as fc:
221
+ series = fc.series(category="crypto") # discover canonical series and assets
222
+ calendar = fc.crypto_calendar(asset="ethereum")
223
+ nxt = fc.next("ethereum-network-upgrades", asset="ethereum")
224
+ rows = list(fc.iter_calendar("2026-10-01", "2027-03-01", category="crypto", asset="ethereum"))
225
+ ```
226
+
227
+ `asset` passes through `calendar`, `calendar_csv`, `iter_calendar`, `today`,
228
+ `week`, `next`, `series`, `series_detail` and `history`. Asset IDs are canonical
229
+ names such as `ethereum`, not ticker symbols such as ETH. Crypto rows have
230
+ `country=None` and may have `impact=None`. A country filter excludes global rows.
231
+
232
+ Estimated month/quarter/year windows retain `date_window_start/end`; `date` is
233
+ only their lower-bound index. Range queries include overlapping windows, and
234
+ `iter_calendar` deduplicates stable IDs across chunks. A scheduled testnet fork
235
+ is distinct from mainnet and is not proof of an observed activation. Inspect
236
+ `crypto.environment`, `crypto.activation_status`, `verification_url`,
237
+ `verification_method`, `manually_reviewed_at`, `last_verified_at` and `data_stale`.
238
+
239
+ `to_dataframe` retains nested `assets`, `crypto`, `source_license` and
240
+ `source_rights` plus the optional `discovery_url`, parses
241
+ estimated date-window bounds, and adds `asset_ids`, `asset_symbols`,
242
+ `crypto_event_type`, `crypto_network`, `crypto_exchange`, `crypto_environment`
243
+ and `crypto_activation_status`. It preserves null countries and recorded zeros.
244
+
245
+ ```sh
246
+ financecalendar series --category crypto
247
+ financecalendar calendar --category crypto --asset ethereum --json
248
+ financecalendar next ethereum-network-upgrades --asset ethereum --tz UTC
249
+ ```
250
+
251
+ Coverage includes network schedules, vesting installments, governance voting
252
+ deadlines and issuer supply projections. The `crypto` object retains source
253
+ metadata:
254
+
255
+ - Unlocks: `schedule_id`, `installment`, `beneficiaries`, `unlock_status`, `date_basis`, `token_amount` and `token_amount_basis` when supplied. Scheduled or upper-bound quantities do not prove transfer or sale.
256
+ - Governance: `dao`, `space_id`, `proposal_id`, optional `proposal_title`, `voting_start`, `voting_end`, `voting_state`, `voting_type` and `choice_count`. A voting deadline is not approval, rejection or execution.
257
+ - Supply projections: `projection_status`, `projected_circulating_supply`, `projected_monthly_supply_change` and `date_basis`. Issuer estimates are not confirmed unlocks or observed circulating supply; decimal strings retain source precision.
258
+
259
+ Public records combine licensed feeds and independently normalised factual
260
+ records. `source_license` carries actual upstream licensing requirements;
261
+ `source_rights` carries factual provenance, access basis, review time,
262
+ attribution and notice without asserting a publisher copyright licence. Either
263
+ may be null. An optional `discovery_url` is a discovery-page link, potentially
264
+ from an aggregator, and is separate from primary `source_url` and verification
265
+ evidence. CoinMarketCal internal API evaluation payloads are excluded. Coverage
266
+ varies by asset and source; empty results do not establish comprehensive coverage.
267
+
268
+ Raw JSON, `calendar_csv` and CLI `--csv` retain these fields; CSV stores nested
269
+ objects as JSON cells. Preserve record-level rights and licence metadata when
270
+ sharing data. PatternPlus records require the linked credit
271
+ [Data: PatternPlus](https://pattern.plus), carried in
272
+ `source_license.attribution` and `source_license.attribution_url`, alongside the
273
+ licence link and adaptation notice. Human CLI output includes source credits,
274
+ attribution links and factual notices, but remains a summary; use JSON/CSV to
275
+ retain every metadata field when redistributing.
276
+
277
+ ## CLI
278
+
279
+ ```sh
280
+ financecalendar next fomc
281
+ financecalendar next cpi --country uk --tz Europe/London
282
+ financecalendar today
283
+ financecalendar week --next --impact high
284
+ financecalendar calendar --from 2026-11-01 --to 2026-11-30 --country us,gb --holidays
285
+ financecalendar calendar --from 2026-11-01 --to 2026-11-30 --csv > november.csv
286
+ financecalendar series --country gb
287
+ financecalendar show boe
288
+ financecalendar history us-cpi --limit 12
289
+ financecalendar holidays lse 2027
290
+ financecalendar status hkex
291
+ financecalendar changes --since 2026-10-18T00:00:00Z
292
+ financecalendar countries
293
+ financecalendar health
294
+ ```
295
+
296
+ Add `--json` to any command for the raw response. Global options (accepted before or after the command): `--json`, `--tz ZONE`, `--api-key KEY`, `--base-url URL` and `--version`. `health` prints the API's own `/status` (snapshot age and counts). Times are shown in your local zone unless you pass `--tz`:
297
+
298
+ ```
299
+ $ financecalendar --tz America/New_York next fomc
300
+ Wed 28 Oct 14:00 ET FOMC Rate Decision (US) cons. Hold at 3.50-3.75% prior Hold
301
+ https://www.financecalendar.com/event/fomc-rate-decision-october-2026/
302
+ ```
303
+
304
+ ## Data terms
305
+
306
+ Free Developer provides the bounded schedule scope above; richer data and wider features require a paid plan. Use is subject to the current [API service terms](https://www.financecalendar.com/api/terms/) and applicable source terms and credits. Include a visible link to [financecalendar.com](https://www.financecalendar.com) wherever the data appears. Retain each record's `source_license` requirements, including `attribution_url`, source and licence links, full notices and adaptation labels; PatternPlus records require [Data: PatternPlus](https://pattern.plus). Preserve `source_rights` attribution, evidence, access basis and notice for independently normalised facts. This rights metadata does not assert a publisher copyright licence. Earnings dates are not included. Full terms, rate limits and the changelog: [financecalendar.com/api](https://www.financecalendar.com/api/).
307
+
308
+ ## Source and issues
309
+
310
+ [Client source and tests](https://github.com/awarenessdays/financecalendar-api/tree/main/clients/python) · [Report an issue](https://github.com/awarenessdays/financecalendar-api/issues).
311
+
312
+ ## Development
313
+
314
+ ```sh
315
+ python3 -m venv .venv
316
+ .venv/bin/pip install -e ".[test]"
317
+ .venv/bin/python -m pytest -q # offline: every request is answered by httpx.MockTransport fixtures
318
+ .venv/bin/python -m build # wheel + sdist into dist/
319
+ ```
320
+
321
+ Client source code: MIT, Awareness Days Ltd / financecalendar.com. The code licence does not license upstream data; data terms and record-level rights metadata apply separately.
322
+
323
+ ## Official numerical observations
324
+
325
+ Where a result is explicitly mapped, responses retain `observations`,
326
+ `observation_status`, `observation_metric_id` and `observation_fields`. Each
327
+ observation identifies its value, unit, reference period, source, engine capture
328
+ time and any revisions. The previous value uses the previous reference period
329
+ at the current observed vintage; it is not a reconstructed original first print.
330
+ Numerical-source staleness is separate from calendar schedule staleness.
331
+ Text output explains this distinction and retains source credits; JSON and CSV
332
+ retain the available lineage. Unknown consensus stays absent. See the
333
+ [REST reference](https://www.financecalendar.com/api/reference/) for the contract.
334
+
335
+ Expanded US coverage brings consensus forecasts and release results together for
336
+ CPI, nonfarm payrolls, PPI, retail sales, headline PCE, ISM Manufacturing,
337
+ industrial production, Consumer Confidence, JOLTS, ADP employment, ISM Services
338
+ and goods-and-services Trade Balance. Inspect each value's source, reference
339
+ period and recorded edition through its numerical evidence. Official observations
340
+ retain priority for mapped actual/prior values.
341
+ BLS payroll `value` is already converted to jobs. `source_value` remains in
342
+ `source_unit` thousands of jobs with `conversion_factor="1000"`; do not multiply
343
+ the canonical value again. `publisher_reported_revisions` retains publisher units
344
+ and is separate from engine-observed `revision_history`. Neither establishes
345
+ original first prints. Preserve document manifests, occurrence bindings and
346
+ record-level source credits when reusing data.
347
+
348
+ ### Query quality and observation evidence
349
+
350
+ The current Python client includes methods for inspecting data quality and publication evidence.
351
+
352
+ ```python
353
+ with Client() as fc:
354
+ quality = fc.quality()
355
+ evidence = fc.observations(series="us-cpi", role="actual", limit=100)
356
+ for row in evidence["observations"]:
357
+ print(row["event_id"], row["observation"])
358
+ ```
359
+
360
+ Both methods use the same API key, quotas and `FinanceCalendarError` handling as
361
+ the calendar. They return unmodified nested JSON, including source lineage,
362
+ engine-observed revision history, null values and recorded zeros. `quality()`
363
+ reports the current engine snapshot; `observations()` returns validated evidence
364
+ per event and role, including retained stale observations where endorsed by the
365
+ engine contract. Missing evidence does not establish that a release has no result.
366
+
367
+ For observation paging, pass `offset=page["next_offset"]` together with
368
+ `snapshot_generated_at=page["snapshot_generated_at"]` and the identical filters
369
+ while `has_more` is true. On HTTP 409, restart at offset zero against the current
370
+ snapshot. An `observation_id` can occur in several event/role entries.
371
+
372
+ These are **engine-observed current vintages**. They do not reconstruct original
373
+ first prints or arbitrary historical knowledge. The API rejects `as_of`; the
374
+ client passes it through so callers receive the server's normal HTTP 400 error.
375
+
376
+ ## Korean official calendars
377
+
378
+ Filter with `country=KR` (aliases `korea` and `south korea`) or a `kr-` series
379
+ code. MODS and BOK schedules retain explicit reference periods and release
380
+ stages; unsupported or ambiguous identities are withheld. Coverage ends at the
381
+ publisher's verified horizon: a year selector does not establish published dates.
382
+
383
+ These records currently have date precision and `all_day=false`. BOK's raw
384
+ media-publication clock is carried in `source_clock`, distinct from ECOS
385
+ availability. Its timezone has not been explicitly verified, so `release_at_utc`
386
+ and local display time remain null. `release_tz=Asia/Seoul` identifies the calendar
387
+ jurisdiction; do not use it to manufacture an instant. Numerical results and
388
+ consensus remain null until separately verified by an implemented result source.
389
+
390
+ ## Indian official release dates
391
+
392
+ MoSPI dates use `country=IN` and `in-` series codes. Publisher-planned dates remain
393
+ estimated, with no computed holiday adjustment or clock. The source's explicitly
394
+ recorded publication dates take precedence. A publication month is not the
395
+ measured month: `period` and `source_reference_period` stay null where omitted.
396
+ GDP publications may bundle multiple quarterly/annual estimate components;
397
+ these retain their original description and do not imply one headline result.
398
+ Reference-year conflicts and indistinguishable release identities are held for
399
+ review. Inspect per-source health and the verified fiscal-year horizon.
400
+
401
+ ## Historical archive CLI and Python
402
+
403
+ Historical archive access: Starter includes one year, Build includes ten years, and Scale includes all available history. Stored depth varies by exact measure and source. Free Developer excludes the archive. The existing recent-event `/history` route and curated datasets retain their established access; previous agreements are preserved. These commands use paged JSON within the server-authorized window. Scale can traverse all available archive history; its complete current snapshot download is a separate feature.
404
+
405
+ Inspect coverage first. Its rows expose `accessible_range.from`, `accessible_range.to` and `date_basis`, alongside full stored metadata; top-level `access` describes your effective rolling UTC calendar-year window. Omitting date bounds below uses the authorized range. Explicit dates before your plan floor return HTTP403.
406
+
407
+ ```sh
408
+ financecalendar history-coverage --source-id ons --all
409
+ financecalendar archive-observations --metric-id gb-cpi-all-items-yoy --limit 100 --all
410
+ financecalendar archive-releases --series-code gb-cpi --limit 100
411
+ ```
412
+
413
+ Each command returns JSON with exact decimal strings, nulls, source/vintage
414
+ metadata, archive revision and continuation. Observation date bounds apply to
415
+ the measured reference-period start; release bounds apply to publication dates.
416
+ One page is returned by default. Continue with `--cursor` and identical original
417
+ filters/limit. `--all` buffers every page before printing: a changed revision,
418
+ invalid continuation or request failure produces no partial success. The
419
+ optional `--as-of` uses FC's durable-evidence receipt bound and does not establish
420
+ original market availability. Check `history-coverage` for actual stored depth;
421
+ these clients do not promise twenty years for every metric.
422
+
423
+ For a Scale key and a measure with stored coverage extending that far, an explicit long-range request can use `--from 2006-01-01`. Check `accessible_range` first; available depth is measure-specific. Scale history uses the same paged JSON retrieval.
424
+
425
+ ## Dated source editions and historical survey forecasts
426
+
427
+ Explore numerical values in named source editions with `/history/editions` and typed public survey aggregates with `/history/forecasts`. Start with `/history/vintage-coverage` to inspect each exact metric’s stored scope and your key’s `accessible_range`. **Starter includes one year, Build ten years, and Scale all available history**; omit date bounds to use your plan window. Depth varies by metric/source. Free Developer excludes these routes; existing legacy routes and agreements keep their established access.
428
+
429
+ Edition `from`/`to` filters use publication day; edition access also requires the measured reference-period start inside the plan window. A newly published edition does not grant older measured periods beyond your plan. Forecast filters use `issue_period_start`, an ordering index; `reference_period` describes the separate target. Preserve `forecast_type`, aggregation, target definition, native horizon, exact decimal strings, nulls, units, scale and source credits. Published survey aggregates are distinct from event-matched market consensus and FC blends. Historical survey databases may contain publisher corrections; they are not automatically unchanged original archived issues. Inspect `first_print_status`, `first_print_rule_id`, native stage and correction status for source editions.
430
+
431
+ `as_of` replays Finance Calendar’s durable receipt versions. `available_before` is a separate strict source-public-availability cutoff: provide exact UTC seconds ending in `Z`; unknown, date-only and coarse issue clocks are excluded. A valid query may return no rows. These source cutoffs test the selected FC capture version and do not silently fall back to a different earlier capture. Future/coarse/naive cutoffs are rejected. Follow `next_cursor` with the same original filters and limit; on 409 restart and discard partial results.
432
+ ```python
433
+ from financecalendar import Client
434
+
435
+ with Client() as calendar:
436
+ scopes = list(calendar.iter_vintage_coverage(kind="forecasts"))
437
+ metric = next((scope["metric_id"] for scope in scopes
438
+ if (scope.get("accessible_range") or {}).get("from")), None)
439
+ if metric is None:
440
+ raise ValueError("No survey forecasts in this plan window")
441
+ forecasts = list(calendar.iter_archive_forecasts(metric_id=metric, limit=100))
442
+ editions = list(calendar.iter_archive_editions(
443
+ metric_id="us-gdp-real-qoq-saar", limit=100,
444
+ ))
445
+
446
+ # Use an export only after iteration finishes successfully.
447
+ for forecast in forecasts:
448
+ print(forecast["issue_period"], forecast["reference_period"], forecast["value"])
449
+ print(forecast["source_license"]["attribution"])
450
+ ```
451
+
452
+ One-page methods are `archive_editions()`, `archive_forecasts()` and `vintage_coverage()`; complete iterators are `iter_archive_editions()`, `iter_archive_forecasts()` and `iter_vintage_coverage()`. `iter_archive(kind="editions"|"forecasts", ...)` is also supported. A later error makes previously yielded rows partial: buffer or commit only after success. API values remain exact strings/nulls; use `Decimal` explicitly for calculations.
453
+
454
+ ```sh
455
+ financecalendar vintage-coverage --kind forecasts --all
456
+ financecalendar historic-editions --metric-id us-gdp-real-qoq-saar --all
457
+ financecalendar historic-forecasts --metric-id eu-spf-hicp-annual-mean-p12m --all
458
+ ```