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 ORCID iD [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

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

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

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:

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:

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

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:

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:

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