authentication.Rmd

---
title: "Authentication & Options"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Authentication & Options}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

Set up a valid authentication to the 'HERE' REST APIs and optionally configure a proxy.

## Application credentials

In order to use the functionality of the **hereR** package, application credentials for a HERE project must be provided. The HERE application credentials (API Key) can be obtained for free as follows:

1. Go to [developer.here.com](https://developer.here.com/)
2. Sign up for a HERE developer account, which automatically creates a new project 
3. Click 'REST: Generate APP'
4. Click 'Create API Key' and copy the key

The API key is set for the current R session and will be used to authenticate in the requests to the HERE REST APIs (250K free transactions per month).
To set the key, please use:

```{r set}
library(hereR)
set_key("<YOUR API KEY>")
```

Alternatively, the key can be exported directly to the environment: `export HERE_API_KEY="<YOUR-KEY>"`

## Information about requests

By default, the **hereR** package does not print messages with information about the
requests sent and the data received from to the HERE APIs. If this information should be printed for the current R session, use:

```{r set_verbose}
set_verbose(TRUE)
```

Use `set_Verbose(FALSE)` to set the **hereR** package to be quiet again.

## Rate limits

For freemium licenses the number of requests per second (RPS) is limited, use `set_rate_limit(FALSE)` to turn off rate limits for accounts with paid plans.

The limits are: 

Service | Max RPS
-- | --
Geocoding & Search | 5
Multi Reverse Geocoding | 1
Vector Tile | 10
Map Tile | 30
Map Image | 2
Routing | 10
Matrix Routing | 1
Isoline Routing | 1
Route Matching | 1
Advanced Datasets | 10
Waypoints Sequence | 1
Transit | 10
Intermodal | 5

## Proxy

If you are working behind a corporate proxy the requests sent by **hereR** might fail with timeout errors.
In this case, consider setting a global proxy for R. Open the R environment file `file.edit('~/.Renviron')` and add your proxy configuration:

``` sh
http_proxy=http://user:passwd@proxy.dom.com:port/
https_proxy=https://user:passwd@proxy.dom.com:port/
```

**Note:** On RStudio Server this file is located at `R_HOME/etc/Renviron.site`.

## Remove credentials

To remove previously set credentials from the current R session use `unset_key()`.
For overwriting the application credentials use again the `set_key()` function.

## Reference

* [Sign up as developer](https://developer.here.com/sign-up?create=Freemium-Basic&keepState=true&step=account)
* [Pricing and plans](https://developer.here.com/pricing)