API Basics — U.S. Treasury Fiscal Data

Overview

RESTful API — accepts HTTP GET requests only
Returns JSON by default (also CSV, XML)
No API key, no authentication, no registration required
Open data, free for commercial and non-commercial use
Current versions: v1 and v2 (check each dataset's page for which version applies)

URL Structure

BASE URL + ENDPOINT + PARAMETERS

Base URL:  https://api.fiscaldata.treasury.gov/services/api/fiscal_service
Endpoint:  /v2/accounting/od/debt_to_penny
Params:    ?fields=record_date,tot_pub_debt_out_amt&sort=-record_date&page[size]=5

Full URL:
https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/debt_to_penny?fields=record_date,tot_pub_debt_out_amt&sort=-record_date&page[size]=5

Endpoint components use lowercase + underscores
Endpoint names are singular

API Versioning

v1: Earlier datasets (DTS, MTS, some debt tables)
v2: Newer or updated datasets (Debt to Penny, TROR, avg interest rates)
Check the specific dataset page at fiscaldata.treasury.gov/datasets/ to confirm the version

Verifying Endpoint Paths

Endpoint paths change when datasets are restructured. Always confirm the current path on the dataset's API Quick Guide before querying.

Authoritative sources (in order):

Dataset detail page at https://fiscaldata.treasury.gov/datasets/{slug}/
Gatsby page data: https://fiscaldata.treasury.gov/page-data/datasets/{slug}/page-data.json (look for "endpoint" fields)
API endpoint table

Data Types

All field values in responses are strings (quoted), regardless of their logical type.

Logical Type	dataTypes value	Example value	How to convert
String	`STRING`	`"Canada-Dollar"`	No conversion needed
Number	`NUMBER`	`"36123456789012.34"`	`float(value)`
Date	`DATE`	`"2024-03-31"`	`pd.to_datetime(value)`
Currency	`CURRENCY`	`"1234567.89"`	`float(value)`
Integer	`INTEGER`	`"42"`	`int(value)`
Percentage	`PERCENTAGE`	`"4.25"`	`float(value)`

Null values appear as the string "null" (not Python None or JSON null).

# Safe numeric conversion handling nulls
def safe_float(val):
    return float(val) if val and val != "null" else None

HTTP Methods

Only GET is supported
POST, PUT, DELETE return HTTP 405

Rate Limiting

HTTP 429 is returned when rate limited
No documented fixed rate limit; implement retry with backoff for bulk requests

import time
import requests

def get_with_retry(url, params, retries=3):
    for attempt in range(retries):
        resp = requests.get(url, params=params)
        if resp.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        resp.raise_for_status()
        return resp.json()
    raise Exception("Rate limited after retries")

Caching

HTTP 304 (Not Modified) can be returned for cached responses
Safe to cache responses; most datasets update daily, monthly, or quarterly

Pagination Headers

Responses include pagination in two places:

links object in the JSON body (self, first, prev, next, last)
Link HTTP header with RFC 5988 relations (rel="first", rel="next", etc.)

Either can be used to navigate pages programmatically. See response-format.md for details.

Data Registry

The Fiscal Service Data Registry contains field definitions, authoritative sources, data types, and formats across federal government data.