API Documentation

Parameters can be included in an API request by modifying the URL. This will specify the criteria to determine which records will be returned, as well as the ordering and format of the data returned. More information about each parameter can be found below.

Available parameters include:

• Fields
• Filters
• Sorting
• Format
• Pagination

Parameter: fields=

Definition: The fields parameter allows you to select which field(s) should be included in the response.

Accepts: The fields= parameter accepts a comma-separated list of field names.

Required: No, specifying fields is not required to make an API request.

Default: If desired fields are not specified, all fields will be returned.

Notes: When a file name passed to the fields parameter is not available for the endpoint accessed, an error will occur. Note that omitting fields can result in automatically aggregated and summed data results. For more information, view the full documentation on Aggregation and Sums.

Examples:

Only return the following fields from a dataset: country_currency_desc, exchange_rate, and record_date.

Return the following fields from the Treasury Reporting Rates of Exchange dataset: country_currency_desc, exchange_rate, and record_date.

All fields in a response will be treated as strings and enclosed in quotation marks (e.g., "field_name"). The data type listed in a dataset's data dictionary or Fields table in dataset-specific API documentation indicates what the field is meant to be (e.g., date). Note: This includes null values, which will appear as strings ("null") rather than a blank or system-recognized null value. This allows you to convert it to that data type in your language of choice. For example, the Pandas library for Python helps you convert strings to 'datetime objects' and R allows you to convert characters to date objects using as.Date.

To discover what fields are available within each endpoint, check out the corresponding dataset's detail page for dataset-specific API documentation or refer to its data dictionary.

Looking for field names for a specific dataset? Jump to the Endpoints by Dataset section to find your dataset of interest. Select any dataset name to view that dataset's details, including metadata, data dictionary, a preview table, graphs, and more!

Not sure which dataset you need? Head over to our Datasets page to search and filter for datasets by topic, dates available, file type, and more.

Parameter: sort=

Definition: The sort parameter allows a user to sort a field in ascending (least to greatest) or descending (greatest to least) order.

Accepts: The sort parameter sort= accepts a comma-separated list of field names.

Required: No, sorting is not required to make an API request.

Default: When no sort parameter is specified, the default is to sort by the first column listed. Most API endpoints are thus sorted by date in ascending order (historical to most current).

Notes: You can nest sorting by passing the sort= parameter a comma-separated list.

Examples:

Sort the records returned by date in descending order, i.e. starting with the most recent date. ?sort=-record_date

Sort the Treasury Report on Receivables dataset by the Funding Type ID field in ascending order i.e., least to greatest.

Nested sorting (year, then month).

Parameter: format=

Definition: The format parameter allows a user to define the output method of the response (CSV, JSON, XML).

Accepts: The format= parameter accepts xml, json, or csv as an input.

Required: No, format is not required to make an API request.

Default: When no format is specified, the default response format is JSON.

Example:

Return all of the data from the Debt to the Penny dataset in a JSON format.

Parameter: page[size]= and page[number]=

Definition: The page size will set the number of rows that are returned on a request, and page number will set the index for the pagination, starting at 1. This allows the user to paginate through the records returned from an API request.

Accepts: The page[number]= and page[size]= parameters both accept integers.

Required: No, neither pagination parameters are required to make an API request.

Default: When no sort parameter is specified, the default is to sort by the first column listed. Most API endpoints are thus sorted by date in ascending order (historical to most current).

Notes: When no page number or page size parameter is specified, the default response is

• Page number: 1
• Page size: 100

Example:

From the Treasury Offset Program dataset, return data with 50 records per page, and return the 10th page of data.

The response will be formatted according to the format input parameter specified in the Format section and will be json, xml or csv. When format is not specified, the default response will be JSON. The response will be utf-8 and will have gzip support.

The following response codes may be returned:

The meta object provides metadata about the resulting payload from your API request. The object will contain the following:

• count: Record count for the response.
• labels: Mapping from result field to logical field names.
• dataTypes: Data type for each returned field.
• dataFormats: Size or format for each returned field.
• total-count: Total number of rows available in the dataset.
• total-pages: Total number of pages of data available based on the page size in the meta count response.

Example Meta Object:

"meta": {
  "count": 3790,
  "labels": {
    "country_currency_desc": "Country - Currency Description",
    "exchange_rate": "Exchange Rate",
    "record_date": "Record Date"
  },
  "dataTypes": {
    "country_currency_desc": "STRING",
    "exchange_rate": "NUMBER",
    "record_date": "DATE"
  },
  "dataFormats": {
    "country_currency_desc": "String",
    "exchange_rate": "10.2",
    "record_date": "YYYY-MM-DD"
  },
  "total-count": 3790,
  "total-pages": 1
}

The links object is an API argument to access the current (self), first, previous, next, and last page of data. It is suitable for creating URLs under user interface elements such as pagination buttons.

Example Links Object:

"links": {
  "self": "&page%5Bnumber%5D=1&page%5Bsize%5D=-1",
  "first": "&page%5Bnumber%5D=1&page%5Bsize%5D=-1",
  "prev": null,
  "next": null,
  "last": "&page%5Bnumber%5D=1&page%5Bsize%5D=-1"
}

The data object is the section of the response where the requested data will be returned. The other objects (e.g., meta object, links object) are sent to enable use of the requested data.

The data object beings with {"data":

If something goes wrong while creating the API response, an error object will be returned to the user. The error object will contain the following information:

• Error: The error name.

• Message: A detailed explanation of why the error occurred and how to resolve it.

Example Error Object:

{
  "error": "Invalid Query Param",
  "message": "Invalid query parameter 'sorts' with value '[-record_date]'.  For more information please see the documentation."
}

The pagination header will contain the link: header and allows a user to navigate pagination using just the APIs.

Link <url first>; rel="first", <url prev>; rel="prev"; <url next>; rel="next"; <url last>; rel="last"

In some cases, using a field list that excludes some of an endpoint’s available fields will trigger automatic aggregation of non-unique rows and summing of their numeric values, etc. You should use this when searching for the sum total of a specific field.

For example, the API call for the sum total of the opening monthly balance within the Daily Treasury Statement dataset would read as:

Running this API call will yield a sum of all the totals in the selected field. In this case, the call yields the total sum of all opening monthly balances over the course of all dates available in the dataset.

• Return only the following fields:country_currency_desc,exchange_rate, and record_date

• return the following fields:country_currency_desc,exchange_rate, and record_date
• return data only for the Canadian Dollar and Mexican Peso
• return data only if the date is on or after January 1, 2020.

• return the following fields:record_calendar_year,record_calendar_month
• return the most recent data first , i.e., return data sorted by year (descending order) and then month (descending order)

• return all of the data
• return the data in a JSON format

• return the data on the 10th page, and each page returns 50 records of data