treasury-fiscaldata-guide

Scope

Use this server for Treasury fiscal accounts, debt outstanding, the average interest Treasury pays on outstanding securities, and statutory reporting exchange rates. Establish the measure before choosing a dataset: average borrowing costs and reporting exchange rates do not answer questions about current market yields or spot FX.

Identifiers

Resolve an endpoint and its field names through treasury_list_datasets. Its catalog is curated; an absent entry does not establish that Treasury lacks the dataset. For an unlisted endpoint or field, consult Treasury's documentation before querying it.

Read category values from records for the period being studied. A field name identifies a column, not the set of values that column contains; security descriptions and country names must match Treasury's returned vocabulary.

The input canvas_id requests staging; it does not choose a table name or identify a destination canvas. The returned canvas_id is the server-assigned table name. Use that returned name for dataframe inspection and SQL. A SQL result persisted with register_as instead returns its name in registered_as.

Gates

• Establish coverage before calculating a total, minimum, maximum, or trend. A generic dataset query fetches one page, and staging stores only that page. Walk the remaining pages with the same selection and sort, retaining each returned table name. Convenience series can return a short inline preview; compare the response counts and notices, then inspect the staged rows before analyzing the series.
• Verify that each staged table exists and inspect its provenance and schema before SQL. Staging can fail or be unavailable, and tables expire. An absent table requires re-fetching the source data, not inventing a table name.
• Use the staged schema rather than convenience-response property names. For example, a debt response's total_debt corresponds to the raw staged column tot_pub_debt_out_amt; interest responses rename avg_interest_rate_amt to avg_interest_rate_pct inline.
• Align row dates before comparing series. A filtered interest-rate latest result can be the last published month for a discontinued security type. Filtered exchange-rate latest results can span quarters; the top-level newest date does not date every row. Use a common reporting period or disclose the difference.
• Inspect fiscal row structure before aggregating. MTS hierarchy rows and MSPD security roll-ups include totals alongside components. Select a published total or mutually exclusive components; do not sum both. Discover the relevant identifiers and labels from the selected period rather than assuming fixed labels.
• Match units and period basis before combining measures. Some catalog datasets use millions or billions. A monthly amount and a fiscal-year-to-date amount are different measures; summing successive FYTD snapshots counts earlier months repeatedly. Preserve missing values rather than converting the string "null" into zero.
• Check SQL coverage as well as source coverage. row_count_capped means the response count is a cap, not the full result size; a smaller preview can hide additional rows even when the count is exact. Materializing a SQL result cannot restore source pages that were never staged.