---
title: "Introduction to `fixerapi`"
author: "Evan Odell"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to `fixerapi`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Introduction

`fixerapi` is a package for accessing data from the [fixer.io](https://fixer.io) currency exchange rate API. The [fixer.io](https://fixer.io) API requires [registration](https://fixer.io/product) and the use of an API key. Free accounts are limited to 10,000 API calls a month, and can only access the most currency conversion rates, using the Euro as the base currency. For complete details, see the [documentation](https://fixer.io/documentation) on [fixer.io](https://fixer.io).

## Setting a key

Set your [fixer.io](https://fixer.io) API key with the `fixer_api_key()` function, or with `Sys.setenv(FIXER_API_KEY = <key>)`. You can find your key on your [fixer.io dashboard](https://fixer.io/dashboard).

## Setting an account type

If you have a paid account, setting your account type to "paid" with `fixer_account_type("paid")` switches to SSL connections over HTTPS, instead of the HTTP connection used by free accounts. Setting your account type does not have any other effects on your ability to use the [fixer.io](https://fixer.io) API. Features limited to certain levels of account are automatically limited by the Fixer API itself, and will return warning messages indicating as such.

# Using `fixerapi`

To access a `tibble` with the name and currency symbol (a three letter code) for all currencies available through the API, use `fixer_symbols()`.

There are five currency exchange query types, which [fixer.io](https://fixer.io) calls endpoints. They are:

* Current exchange rates, accessed using `fixer_latest()` (available with free account)
* Historical exchange rates on a given date, using `fixer_historical()` (available on all paid accounts)
* Conversion from one currency to another, either currently or on a specific date, using `fixer_convert()` (available on all paid accounts)
* A time series of up to 365 days showing daily exchange rates over that time, using `fixer_time_series()` (available on "professional" and higher grade accounts)
* Exchange rate fluctuations over a period of up to 365 days, using `fixer_fluctuation()` (available on "professional plus" and "enterprise" grade accounts)

With the exception of `fixer_convert()`, which is limited to two currencies, all functions give an option for a base currency that is indexed to 1 and other currencies are compared to -- the default is the Euro -- and an option to limit the currencies it is compared with, using the `symbols` parameter, which takes a character vector of currency symbols. If no symbols are specified, all available currencies are returned.


```{r eval=FALSE}
library(fixer)
today_symbols <- fixer_latest(base = "EUR", 
                              symbols = c("JPY", "GBP", "USD", "CAD", "CHF"))

print(today_symbols)

#> A tibble: 5 x 2
#>   name    value
#>   <chr>   <dbl>
#> 1 JPY   131.   
#> 2 GBP     0.873
#> 3 USD     1.23 
#> 4 CAD     1.57 
#> 5 CHF     1.18 


today_all <- fixer_latest(base = "EUR")

print(today_all)

#> A tibble: 168 x 2
#>    name   value
#>    <chr>  <dbl>
#>  1 AED     4.51
#>  2 AFN    84.9 
#>  3 ALL   130.  
#>  4 AMD   589.  
#>  5 ANG     2.18
#>  6 AOA   263.  
#>  7 ARS    24.7 
#>  8 AUD     1.60
#>  9 AWG     2.18
#> 10 AZN     2.09
#> ... with 158 more rows
```

The example above shows the exchange rates on 2018-04-03.

Free accounts are limited to the `fixer_latest()` function, and cannot change the base currency. Free accounts come with 10,000 calls per month, paid accounts with more, depending on the level of the paid account.

Full documentation for the API itself is available [on the Fixer website](https://fixer.io/documentation), along with the [signup](https://fixer.io/product).