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.
- financecalendar-0.1.8/.gitignore +6 -0
- financecalendar-0.1.8/LICENSE +21 -0
- financecalendar-0.1.8/PKG-INFO +458 -0
- financecalendar-0.1.8/README.md +425 -0
- financecalendar-0.1.8/pyproject.toml +50 -0
- financecalendar-0.1.8/src/financecalendar/__init__.py +17 -0
- financecalendar-0.1.8/src/financecalendar/cli.py +502 -0
- financecalendar-0.1.8/src/financecalendar/client.py +546 -0
- financecalendar-0.1.8/src/financecalendar/py.typed +0 -0
- financecalendar-0.1.8/tests/conftest.py +125 -0
- financecalendar-0.1.8/tests/fixtures/calendar.json +258 -0
- financecalendar-0.1.8/tests/fixtures/calendar_csv.txt +8 -0
- financecalendar-0.1.8/tests/fixtures/calendar_high.json +320 -0
- financecalendar-0.1.8/tests/fixtures/calendar_holidays.json +463 -0
- financecalendar-0.1.8/tests/fixtures/calendar_tz.json +266 -0
- financecalendar-0.1.8/tests/fixtures/changes.json +919 -0
- financecalendar-0.1.8/tests/fixtures/countries.json +101 -0
- financecalendar-0.1.8/tests/fixtures/crypto.json +105 -0
- financecalendar-0.1.8/tests/fixtures/error_429.json +16 -0
- financecalendar-0.1.8/tests/fixtures/error_bad_tz.json +11 -0
- financecalendar-0.1.8/tests/fixtures/error_next_404.json +11 -0
- financecalendar-0.1.8/tests/fixtures/error_series_404.json +11 -0
- financecalendar-0.1.8/tests/fixtures/error_unknown_series.json +11 -0
- financecalendar-0.1.8/tests/fixtures/history_us_cpi.json +137 -0
- financecalendar-0.1.8/tests/fixtures/holidays_lse_2027.json +72 -0
- financecalendar-0.1.8/tests/fixtures/holidays_nyse.json +148 -0
- financecalendar-0.1.8/tests/fixtures/market_status_lse.json +34 -0
- financecalendar-0.1.8/tests/fixtures/market_status_nyse.json +34 -0
- financecalendar-0.1.8/tests/fixtures/next_cpi_uk.json +47 -0
- financecalendar-0.1.8/tests/fixtures/next_fomc.json +47 -0
- financecalendar-0.1.8/tests/fixtures/next_fomc_tz.json +48 -0
- financecalendar-0.1.8/tests/fixtures/openapi.json +8191 -0
- financecalendar-0.1.8/tests/fixtures/series.json +603 -0
- financecalendar-0.1.8/tests/fixtures/series_detail_fomc.json +916 -0
- financecalendar-0.1.8/tests/fixtures/status.json +23 -0
- financecalendar-0.1.8/tests/fixtures/today.json +115 -0
- financecalendar-0.1.8/tests/fixtures/week.json +259 -0
- financecalendar-0.1.8/tests/fixtures/week_next.json +410 -0
- financecalendar-0.1.8/tests/test_archive.py +50 -0
- financecalendar-0.1.8/tests/test_archive_cli.py +85 -0
- financecalendar-0.1.8/tests/test_cli.py +225 -0
- financecalendar-0.1.8/tests/test_client.py +272 -0
- financecalendar-0.1.8/tests/test_crypto.py +145 -0
- financecalendar-0.1.8/tests/test_enrichment_api.py +183 -0
- financecalendar-0.1.8/tests/test_observations.py +72 -0
- financecalendar-0.1.8/tests/test_quality_api.py +78 -0
- financecalendar-0.1.8/tests/test_vintage_archive.py +127 -0
|
@@ -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
|
+
```
|