Package 'ustfd'

Tests if an endpoint is known

Description

See ustfd_tables() for known endpoints.

Usage

endpoint_exists(endpoint)

Arguments

endpoint

character vector

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

endpoint	required string representing an API endpoint
filter	optional list used to subset the data. See filter-syntax for more information.
fields	optional character vector of the fields to be retrieved
sort	optional string or character vector. Ordering defaults to ascending, to specify descending order precede the field name with '-'
page_size	optional integer for pagination
slowly	pause between http requests when set to TRUE
pause	length, in seconds, to pause
quiet	when set to FALSE updates will be output via a message
user_agent	string, optional

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

response	an httr response returned by ustfd_request()
...	additional arguments passed to httr::content

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

endpoint	required string representing an API endpoint
filter	optional list used to subset the data. See filter-syntax for more information.
fields	optional character vector of the fields to be retrieved
sort	optional string or character vector. Ordering defaults to ascending, to specify descending order precede the field name with '-'
page_size	optional integer for pagination
page_number	optional integer for pagination

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

query	list generated by one of the query generating functions
user_agent	string, optional
process_response	function, optional. processes the httr response object. Defaults to ustfd_json_response() which will return the JSON payload parsed into a list
...	further arguments will be passed to process_response when called

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

response

a parsed response returned by ustfd_json_response()

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

response

a parsed response returned by ustfd_json_response()

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

endpoint	required string representing an API endpoint
filter	optional list used to subset the data. See filter-syntax for more information.
fields	optional character vector of the fields to be retrieved
sort	optional string or character vector. Ordering defaults to ascending, to specify descending order precede the field name with '-'
page_size	optional integer for pagination
page_number	optional integer for pagination
user_agent	optional string

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

endpoints

one or more strings representing a valid endpoint

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

datasets

one or more strings representing a valid dataset ID. If present, only endpoints belonging to matching datasets will be returned

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

query

required list

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

---