Skip to content

foryourhealth111-pixel/Vibe-Skills / bundled/skills/usfiscaldata

usfiscaldata

Verified

Query the U.S. Treasury Fiscal Data API for federal financial data including national debt, government spending, revenue, interest rates, exchange rates, and savings bonds. Access 54 datasets and 182 data tables with no API key required. Use when working with U.S. federal fiscal data, national debt tracking (Debt to the Penny), Daily Treasury Statements, Monthly Treasury Statements, Treasury securities auctions, interest rates on Treasury securities, foreign exchange rates, savings bonds, or any U.S. government financial statistics.

references/parameters.md

View on GitHub
# Query Parameters — U.S. Treasury Fiscal Data API

All parameters are optional. Combine them with `&` in the URL query string.

## `fields=` — Select Columns

Returns only the specified fields. Accepts a comma-separated list of field names.

```
?fields=record_date,tot_pub_debt_out_amt
?fields=country_currency_desc,exchange_rate,record_date
```

- If omitted, all fields are returned
- Invalid field names cause an error
- Omitting some fields can trigger **automatic aggregation** (see below)

### Aggregation / Auto-Sum

When the `fields=` parameter excludes some non-numeric fields, the API automatically groups by the remaining fields and sums numeric values.

```python
# Returns sum of transaction amounts grouped by record_date and transaction_type
params = {
    "fields": "record_date,transaction_type,transaction_today_amt"
}
```

## `filter=` — Filter Records

Narrow results by field values. Multiple field filters are **comma-separated in a single `filter=` parameter**.

### Filter Syntax

```
filter=<field>:<operator>:<value>
filter=<field>:<operator>:<value>,<field>:<operator>:<value>
```

### Operators

| Operator | Meaning | Example |
|----------|---------|---------|
| `eq` | Equal to | `filter=record_date:eq:2024-03-31` |
| `lt` | Less than | `filter=exchange_rate:lt:1.5` |
| `lte` | Less than or equal | `filter=record_date:lte:2024-12-31` |
| `gt` | Greater than | `filter=record_fiscal_year:gt:2010` |
| `gte` | Greater than or equal | `filter=record_date:gte:2024-01-01` |
| `in` | Contained in set | `filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso)` |

### Date Filters

Use `YYYY-MM-DD` format for dates:

```
filter=record_date:gte:2024-01-01
filter=record_date:gte:2023-01-01,record_date:lte:2023-12-31
```

### Multi-Field Filters

```
filter=country_currency_desc:in:(Canada-Dollar,Mexico-Peso),record_date:gte:2024-01-01
```

### Common Filter Fields

Most endpoints have these standard date fields:
- `record_date` — The date of the record (YYYY-MM-DD)
- `record_fiscal_year` — Fiscal year (e.g., `2024`)
- `record_fiscal_quarter` — Fiscal quarter (1-4)
- `record_calendar_year` — Calendar year
- `record_calendar_month` — Calendar month (01-12)

## `sort=` — Sort Results

Sort by one or more fields. Prefix `-` for descending order.

```
?sort=-record_date           # Most recent first
?sort=record_date            # Oldest first
?sort=-record_fiscal_year,-record_fiscal_quarter  # Nested sort
```

**Default:** Sorted by the first column (usually `record_date` ascending).

## `format=` — Output Format

```
?format=json    # Default
?format=csv     # Comma-separated values
?format=xml     # XML
```

When using CSV or XML format, the response is the raw file content rather than JSON.

## `page[size]=` and `page[number]=` — Pagination

Controls how many records per page and which page to return.

```
?page[size]=100&page[number]=1    # Default (100 records, page 1)
?page[size]=10000                  # Large page to reduce requests
?page[number]=5&page[size]=50     # 50 records starting at page 5
```

- Default page size: **100**
- Default page number: **1**
- Use `meta.total-pages` in the response to know how many pages exist
- Use `meta.total-count` for total record count

### Fetch All Records

```python
import requests
import pandas as pd

def fetch_all(endpoint, params=None):
    """Fetch all pages and return as DataFrame."""
    params = dict(params or {})
    params["page[size]"] = 10000
    params["page[number]"] = 1
    
    base = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
    all_data = []
    
    while True:
        resp = requests.get(f"{base}{endpoint}", params=params)
        result = resp.json()
        all_data.extend(result["data"])
        
        meta = result["meta"]
        if params["page[number]"] >= meta["total-pages"]:
            break
        params["page[number]"] += 1
    
    return pd.DataFrame(all_data)
```

## Combining Parameters

```python
params = {
    "fields": "country_currency_desc,exchange_rate,record_date",
    "filter": "country_currency_desc:in:(Canada-Dollar,Euro),record_date:gte:2020-01-01",
    "sort": "-record_date",
    "format": "json",
    "page[size]": 100,
    "page[number]": 1
}
resp = requests.get(
    "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/rates_of_exchange",
    params=params
)
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall