| 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
|
| 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
-
>,<Greater-than and lesser-than -
>=,<=Greater-/lesser-than or equal-to -
=Equal to -
inSubset-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 |
pause |
length, in seconds, to pause |
quiet |
when set to |
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. Seeustfd_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 |
... |
additional arguments passed to |
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 |
... |
further arguments will be passed to |
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 |
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 |
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. Seeustfd_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'))