Usfiscaldata

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

# Demonstrates API aggregation; this is NOT a validated cash-flow total.
# Statement subtotals and overlapping categories must be resolved first.
params = {
    "fields": "record_date,transaction_type,transaction_today_amt"
}

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

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

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

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

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

?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

import time
import requests
import pandas as pd

def fetch_all(endpoint, params=None, max_pages=50, max_records=500_000):
    """Return all matching rows or raise on a bound or changed result size."""
    if max_pages < 1 or max_records < 1:
        raise ValueError("Bounds must be positive")
    params = dict(params or {})
    allowed = {"fields", "filter", "sort", "format", "page[size]", "page[number]"}
    if set(params) - allowed:
        raise ValueError(f"Unknown query parameters: {set(params) - allowed}")
    if params.get("format", "json") != "json":
        raise ValueError("fetch_all requires JSON")
    size = int(params.get("page[size]", 1000))
    if size < 1:
        raise ValueError("page[size] must be positive")
    params["page[size]"] = min(size, 10000)  # local request-size policy
    params["page[number]"] = 1
    base = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service"
    rows = []
    expected = None
    for page in range(1, max_pages + 1):
        params["page[number]"] = page
        for attempt in range(3):
            resp = requests.get(base + endpoint, params=params, timeout=30)
            if resp.status_code in (429, 502, 503, 504) and attempt < 2:
                delay = resp.headers.get("Retry-After", "")
                time.sleep(min(float(delay), 60) if delay.isdigit() else 2 ** attempt)
                continue
            resp.raise_for_status()
            break
        result = resp.json()
        if "error" in result:
            raise ValueError(result)
        total = int(result["meta"]["total-count"])
        pages = int(result["meta"]["total-pages"])
        if total > max_records or pages > max_pages:
            raise RuntimeError("Result exceeds bounds; narrow filters or raise limits")
        if expected is not None and total != expected:
            raise RuntimeError("Result count changed during pagination; rerun snapshot")
        expected = total
        rows.extend(result["data"])
        if len(rows) > max_records:
            raise RuntimeError("Result exceeds max_records")
        if page >= pages:
            if len(rows) != expected:
                raise RuntimeError("Incomplete result")
            return pd.DataFrame(rows)
    raise RuntimeError("Reached max_pages before completion")

params = {
    "fields": "country_currency_desc,exchange_rate,record_date,effective_date",
    "filter": "country_currency_desc:in:(Canada-Dollar,Euro Zone-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,
    timeout=30,
)
resp.raise_for_status()