Package 'ustfd' reference manual

Title:	API Client for US Treasury Fiscal Data
Description:	Make requests from the US Treasury Fiscal Data API endpoints.
Authors:	Guillermo Roditi Dominguez [aut, cre]
Maintainer:	Guillermo Roditi Dominguez <[email protected]>
License:	MIT + file LICENSE
Version:	0.4.4.9000
Built:	2024-11-23 03:01:55 UTC
Source:	https://github.com/groditi/ustfd

Tests if an endpoint is known

Description

See ustfd_tables() for known endpoints.

Usage

endpoint_exists(endpoint)
endpoint_exists(endpoint)

Arguments

endpoint

character vector

Value

logical matching input size

Examples

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

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

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)

## 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"
)
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()

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)
## 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()
ustfd_datasets()

Value

tibble

Source

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

Examples

library(ustfd)
ustfd_datasets()



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, ...)
ustfd_json_response(response, ...)

Arguments

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

Value

a list

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

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



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

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)
## 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)
ustfd_response_meta_object(response)

Arguments

response

a parsed response returned by ustfd_json_response()

Value

a list

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)
## 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)
ustfd_response_payload(response)

Arguments

response

a parsed response returned by ustfd_json_response()

Value

a tibble

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)

## 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"
)
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()

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

Examples

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



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

Examples

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



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)
ustfd_url(query)

Arguments

query

required list

Value

a httr url object

Examples


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


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

Package 'ustfd'

Help Index

Tests if an endpoint is known

Description

Usage

Arguments

Value

See Also

Examples

Request filtered API results

Description

Syntax

Operators

Examples

Retrieve multiple pages of Fiscal Data API in a single call

Description

Usage

Arguments

Value

See Also

Examples

Return a table of supported and known datasets

Description

Usage

Value

Source

See Also

Examples

Process JSON Response of a Successful API Query

Description

Usage

Arguments

Value

See Also

Examples

Form a Query

Description

Usage

Arguments

Value

See Also

Examples

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

Description

Usage

Arguments

Value

See Also

Examples

Extract Metadata From Parsed API Response

Description

Usage

Arguments

Value

See Also

Examples

Extract Payload as Table From Parsed API Response

Description

Usage

Arguments

Value

See Also

Examples

Retrieve Fiscal Data API in a single call

Description

Usage

Arguments

Value

See Also

Examples

Return a table of known fields for known endpoints

Description

Usage

Arguments

Details

Value

Source

See Also

Examples

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

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