---
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. Signup for the HERE Platform
2. Create new App using the Credentials Manager
3. Select the Credentials tab, then go to "API Keys" and click "Create API Key"
4. Copy the API key

To set the key, please use:

```{r set}
library(hereR)
set_key("<YOUR API 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). 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_freemium(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

- [Pricing and plans](https://www.here.com/get-started/pricing)