---
title: "Traffic API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Traffic API}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

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

if (requireNamespace("mapview", quietly = TRUE)) {
  mapview::mapviewOptions(
    fgb = FALSE,
    vector.palette = colorRampPalette(c("#FFD700", "#CA0020"))
  )
}

flows <- hereR:::example$flow
incidents <- hereR:::example$incident
```

Real-time traffic flow and incident information based on the 'HERE Traffic' API. The traffic flow data contains speed (`"SP"`) and congestion (jam factor: `"JF"`) information. Traffic incidents contain information about location, time, duration, severity, description and other details.

## Flow

In order to request the traffic flow, areas of interest (AOIs) have to be provided. The AOIs must be an `sf` object containing a polygon or multiple polygons. The response from the HERE Traffic API will be spatially joined on the AOIs and thereby the traffic flows are mapped to the corresponding polygon.

```{r flow, eval=FALSE}
flows <- flow(
  aoi = aoi[1, ]
)
```

Print the (ordered) 'jam factor' of the traffic flow on an interactive leaflet map:

```{r map_flow, eval=FALSE, out.width='100%'}
flows <- flows[order(flows$jam_factor), ]
rownames(flows) <- NULL

if (requireNamespace("mapview", quietly = TRUE)) {
  mapview::mapview(flows,
    zcol = "jam_factor",
    layer.name = "Jam factor",
    map.types = c("Esri.WorldTopoMap"),
    homebutton = FALSE
  )
}
```

## Incidents

AOIs also must be provided in order to request information about traffic incidents in specific regions. The time interval, which defines the traffic incidents that should be considered, can be specitified by the `from` and `to` parameter. The datetime information passed to the function must be a timestamp of type `POSIXct`. By default, no time interval filter is set.

```{r incidents, eval=FALSE}
incidents <- incident(
  aoi = aoi[1, ]
)
```

Print the traffic incidents on an interactive leaflet map:

```{r map_incidents, eval=FALSE, out.width='100%'}
if (requireNamespace("mapview", quietly = TRUE)) {
  mapview::mapview(incidents,
    zcol = "type",
    layer.name = "Incident type",
    map.types = c("Esri.WorldTopoMap"),
    homebutton = FALSE
  )
}
```

## API Reference

- [Flow](https://developer.here.com/documentation/traffic-api/api-reference.html)
- [Incidents](https://developer.here.com/documentation/traffic-api/api-reference.html)