README.Rmd

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

# OSO

The goal of OSO is to provide a straightforward way of reading data into R from the Bureau of Economic Analysis (BEA) and improving discovery of available data sets.

## Installation

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

```{r, message=FALSE, warning=FALSE}
#install.packages("remotes")
remotes::install_github("aberuiz/OSO")
library(OSO)
```

## API Registration

Every function in OSO does require an API key from BEA. You can register for a key on the [BEA Website](https://apps.bea.gov/api/signup/).

For saving your API Key into the environment you can use `setbeaKey`. To permanently store your BEA API Key in .Renviron use the argument 'install = TRUE'.

```{r eval=FALSE}
setbeaKey(APIkey = "<Your 36 character API Key>", install = TRUE)
```

Once you have set up your key OSO will automatically check for your key in the stored environment using `getbeaKey` when you make a request.

Use `getbeaKey` to check what BEA API Key you have stored. You can overwrite an existing key using the argument 'overwrite = TRUE' in `setbeaKey`.

## Available Datasets

Use `beaDatasetList` to view all datasets available through the BEA API.

**Disclaimer** as of this writing, not all datasets can be accessed through OSO. Look below for a list of future development.

```{r example}
beaDatasetList()
```

## Finding Parameters & Values

In this example, we'll focus on accessing the 'Regional' dataset.

Before making a call using `beaRegional` you may want to look at the parameters necessary to make a request.

Using `beaParamList` we can get the list of parameters we can use for the 'Regional' dataset.

```{r}
beaParamList(
  DatasetName = "Regional"
)
```

From here, you are returned all parameters you can use for this dataset.

To get all available Values for each of the above parameters you can use `beaParamValues`.

```{r}
beaParamValues(
  DatasetName = "Regional",
  ParameterName = "TableName"
)
```

For this example we'll look at Real GDP which is Table Value : "CAGDP9"

You can get all available linecodes for the 'Regional' dataset you can run `beaParamValues` and enter 'linecode' for the ParameterName. 
However, an easier command is `beaParamValuesFiltered` which allows you to view linecodes only for your table of interest: "CAGDP9"

```{r}
beaParamValuesFiltered(
  DatasetName = "Regional",
  TargetParameter = "linecode",
  TableName = "CAGDP9"
)
```

## Making the Request

Now we are ready to make a call using `beaRegional` for Real GDP in Construction for the entire United States using geoFips code '00000'.

```{r}
beaRegional(
  TableName = "CAGDP9",
  LineCode = 11,
  GeoFips = "00000",
  Year = 2022
)
```

**Data Notes**
For datasets that include notes they will be provided in the console. See the above request for an example.

## Multiple Values

For 'Regional' datasets you are able to request multiple returns for parameters 'GeoFips' and 'Year'. You must insert values in a comma-delimited string. For requesting all available years you can also insert 'ALL'.

```{r}
beaRegional(
  TableName = "CAGDP9",
  LineCode = 11,
  GeoFips = "00000, 48000",
  Year = "ALL"
)
```

## In Development

  - Improvements to MNE
  - Addition of IntlServTrade
  - Addition of IntlServSTA
  - Allow for XML Responses