Title:	API Client for US Treasury Fiscal Data
Version:	0.4.4
Description:	Make requests from the US Treasury Fiscal Data API endpoints.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.2.3
URL:	https://github.com/groditi/ustfd
BugReports:	https://github.com/groditi/ustfd/issues
Imports:	dplyr, glue (≥ 1.3.1), httr, lubridate (≥ 1.9.2), purrr (≥ 1.0.0), readr, rlang (≥ 1.0.0), tibble, stringr, snakecase (≥ 0.11.0)
Depends:	R (≥ 3.4)
Suggests:	testthat (≥ 3.0.0), jsonlite
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-01-28 01:28:47 UTC; guill
Author:	Guillermo Roditi Dominguez [aut, cre]
Maintainer:	Guillermo Roditi Dominguez <guillermo@newriverinvestments.com>
Repository:	CRAN
Date/Publication:	2024-01-28 14:30:02 UTC

Tests if an endpoint is known

Description

See ustfd_tables() for known endpoints.

Usage

endpoint_exists(endpoint)

Arguments

Value

logical matching input size

See Also

Other ustfd_user: ustfd_all_pages(), ustfd_datasets(), ustfd_query(), ustfd_simple(), ustfd_table_columns(), ustfd_tables()

Examples

library(ustfd)
endpoint_exists('v2/accounting/od/debt_to_penny')

Request filtered API results

Description

Fiscal Data API allows for the filtering of results on the server side, leading to a smaller payload. The combinations of fields and operators supported are not currently defined, so it is suggested you test the desired combinations before relying on them.

Syntax

A filter should be a named list of key-value pairs where the name corresponds to the field that should be filtered and the value is a character vector or a list where the name of an item corresponds to the operator and the value corresponds to the operand. One field may have more than one filter.

Operators

• >, < Greater-than and lesser-than

• >=, <= Greater-/lesser-than or equal-to

• = Equal to

• ⁠in⁠ Subset-of

Examples

## Not run: 
 #records with a record_date no older than 10 days ago
 list(record_date = c('>=' = lubridate::today()-10))

 #records with a record_date between two dates
 list(
   record_date = c('>=' = '2022-01-01'),
   record_date = c('<=' = '2022-12-31')
 )

 #records with a specific record_date
 list(record_date = c('=' = lubridate::today()-2))

 #records where record_date is any of a set of specific dates
 list(
   record_date = list('in' = c('2022-06-13','2022-06-15','2022-06-17')
 )

## End(Not run)

Retrieve multiple pages of Fiscal Data API in a single call

Description

ustfd_all_pages() is similar to ustfd_simple() with the difference that, for requests that generate multiple pages of results, it will request all pages and merge them into a single result.

While care has been taken to optimize ustfd_all_pages(), for requests spanning more than 10 pages you should consider breaking up the call further if memory use is a concern, especially if you are writing the results to disk or a database with atomic transactions.

Usage

ustfd_all_pages(
  endpoint,
  filter = NULL,
  fields = NULL,
  sort = NULL,
  page_size = 10000L,
  slowly = FALSE,
  pause = 0.25,
  quiet = TRUE,
  user_agent = "http://github.com/groditi/ustfd"
)

Arguments

Value

a list containing the following items

• meta - the metadata returned by the API

• data - the payload returned by the API in table form. See ustfd_response_payload()

See Also

Other ustfd_user: endpoint_exists(), ustfd_datasets(), ustfd_query(), ustfd_simple(), ustfd_table_columns(), ustfd_tables()

Examples

## Not run: 
library(ustfd)

exchange_rates <- ustfd_all_pages(
  'v1/accounting/od/rates_of_exchange',
   fields = c(
    'country_currency_desc', 'exchange_rate','record_date','effective_date'
   ),
   filter = list(
     record_date = c('>=' = '2020-01-01'),
     country_currency_desc = list('in' = c('Canada-Dollar','Mexico-Peso'))
   )
)

## End(Not run)

Return a table of supported and known datasets

Description

ustfd_datasets provides details about 34 known datasets for Fiscal Data. A data frame with 34 rows and the following 7 columns:

• dataset - ID of the source dataset (natural key)

• name - name of the source dataset

• summary_text - description of the data set and the data it covers

• earliest_date - the date of the earliest record available for this table

• data_start_year - first year in the data set

• update_frequency - "Daily", "Monthly", "Quarterly", "Semi-Annually", "Annually", "As Needed", "Daily (Discontinued)", "Monthly (Discontinued)"

• notes_and_known_limitations - notes about

Usage

ustfd_datasets()

Value

tibble

Source

https://fiscaldata.treasury.gov/api-documentation/#list-of-endpoints

See Also

Other ustfd_user: endpoint_exists(), ustfd_all_pages(), ustfd_query(), ustfd_simple(), ustfd_table_columns(), ustfd_tables()

Examples

library(ustfd)
ustfd_datasets()

Process JSON Response of a Successful API Query

Description

ustfd_json_response() will process the response to a successful request from Fiscal Data API and translate a JSON object into a R data structure.

Usage

ustfd_json_response(response, ...)

Arguments

Value

a list

See Also

Other ustfd_low_level: ustfd_request(), ustfd_response_meta_object(), ustfd_response_payload(), ustfd_url()

Examples

## Not run: 
library(ustfd)
query <- ustfd_query('v1/accounting/dts/dts_table_2', sort =c('-record_date'))
response <- ustfd_request(query)
payload_table <- ustfd_response_payload(response)
payload_meta <- ustfd_response_meta_object(response)

## End(Not run)

Form a Query

Description

ustfd_query() will verify the endpoint is valid and return a list suitable for passing to ustfd_url() and ustfd_request().

Usage

ustfd_query(
  endpoint,
  filter = NULL,
  fields = NULL,
  sort = NULL,
  page_size = NULL,
  page_number = NULL
)

Arguments

Value

a list

See Also

Other ustfd_user: endpoint_exists(), ustfd_all_pages(), ustfd_datasets(), ustfd_simple(), ustfd_table_columns(), ustfd_tables()

Examples

library(ustfd)
ustfd_query(
  'v2/accounting/od/utf_qtr_yields',
   filter = list(record_date = c('>=' = lubridate::today()-10))
)
ustfd_query(
  'v2/accounting/od/utf_qtr_yields',
   filter = list(record_date = list('in' = c('2020-03-15','2020-03-16','2020-03-17')))
)
ustfd_query(
  'v2/accounting/od/utf_qtr_yields',
   filter = list(record_date = c('=' = '2020-03-15'))
)

Retrieve Data From the U.S. Bureau Of the Fiscal Service API

Description

ustfd_request() will execute queries against the Fiscal Data API. Queries can generated using ustfd_query().

Usage

ustfd_request(
  query,
  user_agent = "http://github.com/groditi/ustfd",
  process_response = ustfd_json_response,
  ...
)

Arguments

Value

a httr response object

See Also

Other ustfd_low_level: ustfd_json_response(), ustfd_response_meta_object(), ustfd_response_payload(), ustfd_url()

Examples

## Not run: 
library(ustfd)
query <- ustfd_query('v1/accounting/dts/dts_table_2', sort =c('-record_date'))
response <- ustfd_request(query)
payload_table <- ustfd_response_payload(response)
payload_meta <- ustfd_response_meta_object(response)

## End(Not run)

Extract Metadata From Parsed API Response

Description

ustfd_response_meta_object() will return the meta object included in a successful API response. The meta object is a list with the following items:

• count - the number of records in the response

• labels - a named list of labels for each field

• dataTypes - a named list describing the data type for each field

• dataFormats - a named list describing the data format for each field

• total-count - the total number of records matching the query

• total-pages - the total number of pages of records matching the query

Usage

ustfd_response_meta_object(response)

Arguments

Value

a list

See Also

Other ustfd_low_level: ustfd_json_response(), ustfd_request(), ustfd_response_payload(), ustfd_url()

Examples

## Not run: 
library(ustfd)
query <- ustfd_query('v1/accounting/dts/dts_table_2', sort =c('-record_date'))
response <- ustfd_request(query)
payload_table <- ustfd_response_payload(response)
payload_meta <- ustfd_response_meta_object(response)

## End(Not run)

Extract Payload as Table From Parsed API Response

Description

ustfd_response_payload() will return the results of the query in tabular format in the form of a tibble with one column for each field returned and one row for every record returned in the same order they were returned.

Usage

ustfd_response_payload(response)

Arguments

Value

a tibble

See Also

Other ustfd_low_level: ustfd_json_response(), ustfd_request(), ustfd_response_meta_object(), ustfd_url()

Examples

## Not run: 
library(ustfd)
query <- ustfd_query('v1/accounting/dts/dts_table_2', sort =c('-record_date'))
response <- ustfd_request(query)
payload_table <- ustfd_response_payload(response)
payload_meta <- ustfd_response_meta_object(response)

## End(Not run)

Retrieve Fiscal Data API in a single call

Description

ustfd_simple() aggregates the workflow for retrieving data from the API into a single call.

Usage

ustfd_simple(
  endpoint,
  filter = NULL,
  fields = NULL,
  sort = NULL,
  page_size = NULL,
  page_number = NULL,
  user_agent = "http://github.com/groditi/ustfd"
)

Arguments

Value

a list containing the following items

• meta - the metadata returned by the API

• data - the payload returned by the API in table form. See ustfd_response_payload()

See Also

Other ustfd_user: endpoint_exists(), ustfd_all_pages(), ustfd_datasets(), ustfd_query(), ustfd_table_columns(), ustfd_tables()

Examples

## Not run: 
library(ustfd)

exchange_rates <- ustfd_simple(
  'v1/accounting/od/rates_of_exchange',
   fields = c(
    'country_currency_desc', 'exchange_rate','record_date','effective_date'
   ),
   filter = list(
     record_date = c('>=' = '2020-01-01'),
     country_currency_desc = list('in' = c('Canada-Dollar','Mexico-Peso'))
   )
)

## End(Not run)

Return a table of known fields for known endpoints

Description

ustfd_table_columns returns the column dictionaries for the specified endpoint(s). See ustfd_tables() for known endpoints.

Usage

ustfd_table_columns(endpoints = NULL)

Arguments

Details

The format of a dictionary is a tibble with one row for every table column and the following columns:

• endpoint - the ID of the table this column belongs to

• colum_name - the field name recognizable to the API interface

• data_type - one of: "DATE", "STRING", "CURRENCY", "NUMBER", "PERCENTAGE", "YEAR", "QUARTER", "MONTH", "DAY"

• pretty_name - a descriptive label

• definition - definition of the colmn's value

• is_required - logical value

Value

tibble

Source

https://fiscaldata.treasury.gov/api-documentation/#fields-by-endpoint

See Also

Other ustfd_user: endpoint_exists(), ustfd_all_pages(), ustfd_datasets(), ustfd_query(), ustfd_simple(), ustfd_tables()

Examples

library(ustfd)
ustfd_table_columns(ustfd_tables(ustfd_datasets()$dataset[2])$endpoint)

Return a table of supported and known tables including the API endpoints for the specified dataset(s). See ustfd_datasets() for known datasets.

Description

ustfd_tables provides details about 85 known endpoints for Fiscal Data. A data frame with 85 rows and the following 9 columns:

• dataset - ID of the source dataset

• endpoint - the table's API endpoint (natural key)

• table_name - Name of the table within the data set

• table_description - a description for the data in the endpoint

• row_definition - a description of what each row in the table describes

• path_name - API path name

• date_column - the name of the table column that holds the record's date

• earliest_date - the date of the earliest record available for this table

• update_frequency - "Daily", "Monthly", "Quarterly", "Semi-Annually", "Annually", "As Needed", "Daily (Discontinued)", "Monthly (Discontinued)"

Usage

ustfd_tables(datasets = NULL)

Arguments

Value

tibble

Source

https://fiscaldata.treasury.gov/api-documentation/#list-of-endpoints

See Also

Other ustfd_user: endpoint_exists(), ustfd_all_pages(), ustfd_datasets(), ustfd_query(), ustfd_simple(), ustfd_table_columns()

Examples

library(ustfd)
ustfd_tables(ustfd_datasets()$dataset[2])$endpoint

Generate URL To Access US Treasury Fiscal Data API

Description

ustfd_url() will generate a URL suitable for querying the Fiscal Data API.

Usage

ustfd_url(query)

Arguments

Value

a httr url object

See Also

Other ustfd_low_level: ustfd_json_response(), ustfd_request(), ustfd_response_meta_object(), ustfd_response_payload()

Examples

library(ustfd)
ustfd_url(ustfd_query('/v1/accounting/dts/dts_table_4'))