Skills › Scientific Agent Skills › usfiscaldata › api-basics.md

api-basics.md

88 lines · skills/usfiscaldata/references/api-basics.md at 5f2bc03

Open on GitHub

1# API Basics — U.S. Treasury Fiscal Data

API Basics — U.S. Treasury Fiscal Data

Raw lines 1 to 2

3## Overview

5- RESTful API — accepts HTTP GET requests only

6- Returns JSON by default (also CSV, XML)

7- No API key, no authentication, no registration required

8- Open data, free for commercial and non-commercial use

9- Current versions: v1 and v2 (check each dataset's page for which version applies)

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)

Raw lines 3 to 10

11## URL Structure

13```

14BASE URL + ENDPOINT + PARAMETERS

16Base URL: https://api.fiscaldata.treasury.gov/services/api/fiscal_service

17Endpoint: /v2/accounting/od/debt_to_penny

18Params: ?fields=record_date,tot_pub_debt_out_amt&sort=-record_date&page[size]=5

20Full URL:

21https://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

22```

24- Endpoint components use lowercase + underscores

25- Endpoint names are singular

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

Raw lines 11 to 26

27## API Versioning

29- **v1**: Earlier datasets (DTS, MTS, some debt tables)

30- **v2**: Newer or updated datasets (Debt to Penny, TROR, avg interest rates)

31- Check the specific dataset page at `fiscaldata.treasury.gov/datasets/` to confirm the version

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

Raw lines 27 to 32

33## Verifying Endpoint Paths

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

37Authoritative sources (in order):

391. Dataset detail page at `https://fiscaldata.treasury.gov/datasets/{slug}/`

402. Site implementation fallback (not a stable API contract): Gatsby page data: `https://fiscaldata.treasury.gov/page-data/datasets/{slug}/page-data.json` (look for `"endpoint"` fields)

413. [API endpoint table](https://fiscaldata.treasury.gov/api-documentation/#list-of-endpoints-table)

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}/
Site implementation fallback (not a stable API contract): Gatsby page data: https://fiscaldata.treasury.gov/page-data/datasets/{slug}/page-data.json (look for "endpoint" fields)
API endpoint table

Raw lines 33 to 42

43## Data Types

45All data-row values in responses are **strings** (quoted), regardless of their logical type.

48|---|---|---|---|

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

58```python

59# Safe numeric conversion handling nulls

60def safe_float(val):

61 return float(val) if val and val != "null" else None

62```

Data Types

All data-row 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"`	`Decimal(value)` for exact amounts; `float(value)` for plots
Date	`DATE`	`"2024-03-31"`	`pd.to_datetime(value)`
Currency	`CURRENCY` or precision variants (`CURRENCY0`, `CURRENCY3`, etc.)	`"1234567.89"`	`Decimal(value)` for exact amounts; `float(value)` for plots
Integer	`INTEGER`	`"42"`	`int(value)`
Percentage	`PERCENTAGE`	`"4.25"`	`Decimal(value)` for exact amounts; `float(value)` for plots

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

Raw lines 43 to 63

64## HTTP Methods

66- **Only GET is supported**

67- The documented data interface is read-only GET; do not assume a particular error code for unsupported methods.

HTTP Methods

Only GET is supported
The documented data interface is read-only GET; do not assume a particular error code for unsupported methods.

Raw lines 64 to 68

69## Reliability and caching

71Use an explicit request timeout and check HTTP status before parsing JSON. No fixed

72request quota is published in the reviewed guide. Respect `Retry-After` on HTTP 429

73and use bounded retries for transient 5xx responses; do not retry invalid filters.

74Save the query, retrieval timestamp, metadata and raw response for reproducibility.

75Historical series can be revised, so cached results need an explicit retrieval date.

Reliability and caching

Use an explicit request timeout and check HTTP status before parsing JSON. No fixed request quota is published in the reviewed guide. Respect Retry-After on HTTP 429 and use bounded retries for transient 5xx responses; do not retry invalid filters. Save the query, retrieval timestamp, metadata and raw response for reproducibility. Historical series can be revised, so cached results need an explicit retrieval date.

Raw lines 69 to 76

77## Pagination Headers

79Responses include pagination in two places:

81- **`links` object** in the JSON body (`self`, `first`, `prev`, `next`, `last`)

82- **`Link` HTTP header** with RFC 5988 relations (`rel="first"`, `rel="next"`, etc.)

84JSON links may be `&page...` fragments, not complete URLs. Preserve the original endpoint, filters, fields and sort while changing the page number; do not replace the query with the fragment. See [response-format.md](response-format.md) for details.

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.)

JSON links may be &page... fragments, not complete URLs. Preserve the original endpoint, filters, fields and sort while changing the page number; do not replace the query with the fragment. See response-format.md for details.

Raw lines 77 to 85

86## Data Registry

88The [Fiscal Service Data Registry](https://fiscal.treasury.gov/data-registry/index.html) contains field definitions, authoritative sources, data types, and formats across federal government data.

Data Registry

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

Raw lines 86 to 88