mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-27 07:09:27 +08:00
137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# Metadata Endpoints
|
|
|
|
## 1. List Mnemonics — `/metadata/mnemonics`
|
|
|
|
**URL:** `GET https://data.financialresearch.gov/hf/v1/metadata/mnemonics`
|
|
|
|
Returns all series identifiers available through the API.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `dataset` | string | No | Filter by dataset key: `fpf`, `tff`, `scoos`, `ficc` |
|
|
| `output` | string | No | `by_dataset` — returns a hash grouped by dataset |
|
|
|
|
### Examples
|
|
|
|
```python
|
|
import requests
|
|
BASE = "https://data.financialresearch.gov/hf/v1"
|
|
|
|
# All mnemonics (flat list)
|
|
resp = requests.get(f"{BASE}/metadata/mnemonics")
|
|
mnemonics = resp.json()
|
|
# Returns: ["FPF-ALLQHF_CDSDOWN250BPS_P5", "FPF-ALLQHF_CDSDOWN250BPS_P50", ...]
|
|
|
|
# Mnemonics for a single dataset with names
|
|
resp = requests.get(f"{BASE}/metadata/mnemonics", params={"dataset": "fpf"})
|
|
# Returns: [{"mnemonic": "FPF-ALLQHF_CDSDOWN250BPS_P5", "series_name": "Stress test: CDS spreads decrease 250 basis points net impact on NAV (5th percentile fund)"}, ...]
|
|
|
|
# All mnemonics grouped by dataset
|
|
resp = requests.get(f"{BASE}/metadata/mnemonics", params={"output": "by_dataset"})
|
|
grouped = resp.json()
|
|
# Returns: {"ficc": [{mnemonic, series_name}, ...], "fpf": [...], ...}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Single Series Query — `/metadata/query`
|
|
|
|
**URL:** `GET https://data.financialresearch.gov/hf/v1/metadata/query`
|
|
|
|
Returns full metadata for a single mnemonic.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `mnemonic` | string | **Yes** | The series mnemonic |
|
|
| `fields` | string | No | Comma-separated list of fields to retrieve. Use `/` to access subfields (e.g., `release/long_name`) |
|
|
|
|
### Metadata Fields
|
|
|
|
The metadata object includes these top-level fields (with subfields):
|
|
|
|
| Field | Subfields |
|
|
|-------|-----------|
|
|
| `mnemonic` | — |
|
|
| `description` | `name`, `description`, `notes`, `vintage_approach`, `vintage`, `subsetting`, `subtype` |
|
|
| `schedule` | `observation_period`, `observation_frequency`, `seasonal_adjustment`, `start_date`, `last_update` |
|
|
| `release` | `long_name`, `short_name`, and other release-level metadata |
|
|
|
|
### Examples
|
|
|
|
```python
|
|
# Full metadata
|
|
resp = requests.get(f"{BASE}/metadata/query", params={
|
|
"mnemonic": "fpf-allqhf_cdsup250bps_p5"
|
|
})
|
|
meta = resp.json()
|
|
print(meta["description"]["name"])
|
|
print(meta["schedule"]["start_date"])
|
|
print(meta["schedule"]["observation_frequency"])
|
|
|
|
# Specific subfield only
|
|
resp = requests.get(f"{BASE}/metadata/query", params={
|
|
"mnemonic": "fpf-allqhf_cdsup250bps_p5",
|
|
"fields": "release/long_name"
|
|
})
|
|
# Returns: {"release": {"long_name": "Hedge Fund Aggregated Statistics from SEC Form PF Filings"}}
|
|
|
|
# Multiple fields
|
|
resp = requests.get(f"{BASE}/metadata/query", params={
|
|
"mnemonic": "fpf-allqhf_cdsup250bps_p5",
|
|
"fields": "description/name,schedule/start_date,schedule/observation_frequency"
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Series Search — `/metadata/search`
|
|
|
|
**URL:** `GET https://data.financialresearch.gov/hf/v1/metadata/search`
|
|
|
|
Full-text search across all metadata fields. Supports wildcards.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Description |
|
|
|-----------|------|----------|-------------|
|
|
| `query` | string | **Yes** | Search string. Supports `*` (multi-char wildcard) and `?` (single-char wildcard) |
|
|
|
|
### Response Fields
|
|
|
|
Each result object contains:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `mnemonic` | Series identifier (or `"none"` for dataset-level metadata) |
|
|
| `dataset` | Dataset key (`fpf`, `tff`, `scoos`, `ficc`) |
|
|
| `field` | Which metadata field matched (e.g., `description/name`) |
|
|
| `value` | The matched field value |
|
|
| `type` | Data type (`str`, etc.) |
|
|
|
|
### Examples
|
|
|
|
```python
|
|
# Find series containing "leverage" anywhere
|
|
resp = requests.get(f"{BASE}/metadata/search", params={"query": "*leverage*"})
|
|
results = resp.json()
|
|
for r in results:
|
|
print(r["mnemonic"], r["field"], r["value"])
|
|
|
|
# Find series starting with "Fund"
|
|
resp = requests.get(f"{BASE}/metadata/search", params={"query": "Fund*"})
|
|
|
|
# Find by exact dataset name
|
|
resp = requests.get(f"{BASE}/metadata/search", params={"query": "FICC*"})
|
|
|
|
# Search for stress test series
|
|
resp = requests.get(f"{BASE}/metadata/search", params={"query": "*stress*"})
|
|
|
|
# Get unique mnemonics from search results
|
|
results = resp.json()
|
|
mnemonics = list({r["mnemonic"] for r in results if r["mnemonic"] != "none"})
|
|
```
|