tools-only API Overview
Base URL & Versioning
https://data.financialresearch.gov/hf/v1
The API version (v1) is required in the URL path. Currently only v1 is available.
Protocol & Format
- All requests use HTTPS
- All responses are JSON (except
/categorieswhich returns CSV) - No authentication, API keys, or registration required
- No documented rate limits — data updates at most once per day; avoid hammering the API
Response Patterns
Most endpoints return one of:
- An array of
[date, value]pairs for time series data - A JSON object keyed by mnemonic for full series (timeseries + metadata)
- A JSON array of objects for search/metadata listings
Timeseries array
[
["2013-03-31", -3.0],
["2013-06-30", -2.0],
["2013-09-30", -2.05]
]
Null values appear as null in the value position.
Full series object
{
"FPF-ALLQHF_NAV_SUM": {
"timeseries": {
"aggregation": [["2013-03-31", 1143832916], ...]
},
"metadata": {
"mnemonic": "FPF-ALLQHF_NAV_SUM",
"description": {
"name": "All funds: net assets (sum dollar value)",
"description": "...",
"notes": "...",
"vintage_approach": "Current vintage, as of last update",
"vintage": "",
"subsetting": "None",
"subtype": "None"
},
"schedule": {
"observation_period": "Quarterly",
"observation_frequency": "Quarterly",
"seasonal_adjustment": "None",
"start_date": "2013-03-31",
"last_update": ""
}
}
}
}
Mnemonic Format
Mnemonics are unique identifiers for each time series. Format varies by dataset:
| Dataset | Pattern | Example |
|---|---|---|
| fpf | FPF-{SCOPE}_{METRIC}_{STAT} |
FPF-ALLQHF_NAV_SUM |
| ficc | FICC-{SERIES} |
FICC-SPONSORED_REPO_VOL |
| tff | TFF-{SERIES} |
TFF-DLRINDEX_NET_SPEC |
| scoos | SCOOS-{SERIES} |
varies |
Mnemonics are case-insensitive in query parameters (the API normalizes to uppercase in responses).
Subseries (label)
Each mnemonic can have multiple subseries labeled:
aggregation— the main data series (always present, default returned)disclosure_edits— version of the data with certain values masked for disclosure protection
Installation
uv add requests pandas
No dedicated Python client exists — use requests directly.