mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-27 07:09:27 +08:00
127 lines
3.6 KiB
Markdown
127 lines
3.6 KiB
Markdown
# Series Data Endpoints
|
|
|
|
## 1. Single Timeseries — `/series/timeseries`
|
|
|
|
**URL:** `GET https://data.financialresearch.gov/hf/v1/series/timeseries`
|
|
|
|
Returns date/value pairs for a single series.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `mnemonic` | string | **Yes** | Series identifier |
|
|
| `label` | string | No | Subseries: `aggregation` (default) or `disclosure_edits` |
|
|
| `start_date` | string | No | First date `YYYY-MM-DD` (default: `1901-01-01`) |
|
|
| `end_date` | string | No | Last date `YYYY-MM-DD` (default: today) |
|
|
| `periodicity` | string | No | Resample to frequency (see parameters.md) |
|
|
| `how` | string | No | Aggregation method: `last` (default), `first`, `mean`, `median`, `sum` |
|
|
| `remove_nulls` | string | No | `true` to remove null values |
|
|
| `time_format` | string | No | `date` (YYYY-MM-DD, default) or `ms` (epoch milliseconds) |
|
|
|
|
### Response
|
|
|
|
Array of `[date_string, value]` pairs. Values are floats or `null`.
|
|
|
|
```json
|
|
[
|
|
["2013-03-31", -3.0],
|
|
["2013-06-30", -2.0],
|
|
["2013-09-30", null],
|
|
["2013-12-31", -3.0]
|
|
]
|
|
```
|
|
|
|
### Examples
|
|
|
|
```python
|
|
import requests
|
|
import pandas as pd
|
|
|
|
BASE = "https://data.financialresearch.gov/hf/v1"
|
|
|
|
# Full history for a series
|
|
resp = requests.get(f"{BASE}/series/timeseries", params={
|
|
"mnemonic": "FPF-ALLQHF_LEVERAGERATIO_GAVWMEAN"
|
|
})
|
|
data = resp.json()
|
|
df = pd.DataFrame(data, columns=["date", "leverage"])
|
|
df["date"] = pd.to_datetime(df["date"])
|
|
|
|
# Filtered date range with null removal
|
|
resp = requests.get(f"{BASE}/series/timeseries", params={
|
|
"mnemonic": "FPF-ALLQHF_NAV_SUM",
|
|
"start_date": "2018-01-01",
|
|
"end_date": "2024-12-31",
|
|
"remove_nulls": "true"
|
|
})
|
|
|
|
# Annual frequency (calendar year end)
|
|
resp = requests.get(f"{BASE}/series/timeseries", params={
|
|
"mnemonic": "FPF-ALLQHF_GAV_SUM",
|
|
"periodicity": "A",
|
|
"how": "last"
|
|
})
|
|
|
|
# Epoch milliseconds for charting libraries
|
|
resp = requests.get(f"{BASE}/series/timeseries", params={
|
|
"mnemonic": "FICC-SPONSORED_REPO_VOL",
|
|
"time_format": "ms"
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Series Spread — `/calc/spread`
|
|
|
|
**URL:** `GET https://data.financialresearch.gov/hf/v1/calc/spread`
|
|
|
|
Returns the difference (spread) between two series: `x - y`. Useful for comparing rates or examining basis relationships.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `x` | string | **Yes** | Base series mnemonic |
|
|
| `y` | string | **Yes** | Subtracted series mnemonic |
|
|
| `start_date` | string | No | Start date `YYYY-MM-DD` |
|
|
| `end_date` | string | No | End date `YYYY-MM-DD` |
|
|
| `periodicity` | string | No | Resample frequency |
|
|
| `how` | string | No | Aggregation: `last`, `first`, `mean`, `median`, `sum` |
|
|
| `remove_nulls` | string | No | `true` to remove nulls |
|
|
| `time_format` | string | No | `date` or `ms` |
|
|
|
|
### Response
|
|
|
|
Array of `[date, value]` pairs where value = x - y at each date.
|
|
|
|
```json
|
|
[
|
|
["2020-01-02", 0.15],
|
|
["2020-03-03", -0.37],
|
|
["2020-04-01", 0.60]
|
|
]
|
|
```
|
|
|
|
### Examples
|
|
|
|
```python
|
|
# Spread between two repo rates
|
|
resp = requests.get(f"{BASE}/calc/spread", params={
|
|
"x": "REPO-GCF_AR_G30-P",
|
|
"y": "REPO-TRI_AR_AG-P",
|
|
"start_date": "2019-01-01",
|
|
"remove_nulls": "true"
|
|
})
|
|
spread = pd.DataFrame(resp.json(), columns=["date", "spread_bps"])
|
|
spread["date"] = pd.to_datetime(spread["date"])
|
|
|
|
# Annual spread with mean aggregation
|
|
resp = requests.get(f"{BASE}/calc/spread", params={
|
|
"x": "FPF-STRATEGY_EQUITY_LEVERAGERATIO_GAVWMEAN",
|
|
"y": "FPF-STRATEGY_CREDIT_LEVERAGERATIO_GAVWMEAN",
|
|
"periodicity": "A",
|
|
"how": "mean"
|
|
})
|
|
```
|