README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# ustfd

<!-- badges: start -->
<!-- badges: end -->

The goal of ustfd is to make it easier to interact with the US Treasury Fiscal
Data API.

## A Bit Of Housekeeping

`ustfd` is a volunteer effort undertaken in my spare time. I have a family and
the little spare time I have is valuable. Please consider sponsoring this
project with a one-time or recurring donation if you would like new
functionality to be added, or just as a show of appreciation. Additionally, if
you or your organization intend to use this package for commercial purposes, I
am open to consulting and/or contract work.

## Installation

You can install the development version of ustfd from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("groditi/ustfd")
```

## Getting Started

`ustfd` provides functions for retrieving and processing data from the Fiscal Data
API. There is 4 steps to the workflow:

  * form a query using `ustfd_query`
  * make an API request using `ustfd_request` 
  * extract metadata about the results using `ustfd_response_meta_object`
  * extract the payload of the response using `ustfd_response_payload`

The function `ustfd_simple` aggregates all 4 steps into a single function call
and should cover most use cases. Dealing with pagination is left to the user.

A list of supported endpoints can be retrieved with `ustfd_tables` and a
dictionary of fields available for each endpoint can be retrieved with
`ustfd_table_columns`.    

## Example

This is a basic example which shows how to retrieve data:

```{r example}
 library(ustfd)
 library(dplyr, warn.conflicts = FALSE)

 interest_rates <- ustfd_simple(
   'v2/accounting/od/avg_interest_rates',
    fields = c(
     'record_date', 'security_desc','security_type_desc','avg_interest_rate_amt'
    ),
    filter = list(
      record_date = c('=' = '2020-03-31')
    ),
   page_size = 20
 )
 
 select(interest_rates$data, -record_date)
```

An example of how to use the field dictionaries:

```{r example2}
 library(ustfd)
 library(dplyr, warn.conflicts = FALSE)

 select(ustfd_table_columns('v2/accounting/od/avg_interest_rates'), -endpoint, -definition)
```

An example of how to use multiple filters:
```{r example3}
 library(ustfd)
 library(dplyr, warn.conflicts = FALSE)

 interest_rates <- ustfd_simple(
    'v2/accounting/od/avg_interest_rates',
    fields = c(
        'record_date', 'security_desc','security_type_desc','avg_interest_rate_amt'
    ),
    filter = list(
        record_date = c('>=' = '2020-03-31'),
        record_date = c('<=' = '2020-05-31'),
        security_type_desc = c('=' = 'Marketable'),
        avg_interest_rate_amt = c('>=' = 1.0)
    )
)
 
 select(interest_rates$data, -security_type_desc, rate = 'avg_interest_rate_amt')
```