---
title: "Public Transit API"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Public Transit 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)
library(mapview)
library(sf)
mapviewOptions(
  vector.palette = colorRampPalette(
    c("#000004FF", "#420A68FF", "#932667FF", "#DD513AFF", "#FCA50AFF", "#FCFFA4FF")
  )
)
connection_section <- hereR:::example$connection_section
connection_summary <- hereR:::example$connection_summary
stations <- hereR:::example$station
```

Request public transport connections between given points and find stations nearby using the 'HERE Public Transit' API.

## Connections
The function `connection()` allows to request public transport connections from the API. Two types of requests are provided:

* `connection(..., summary = FALSE)`: The public transport connections are returned as multiple sections with the same vehicle and transport mode. Each row represents a section with a detailed route geometry.
* `connection(..., summary = TRUE)`: A summary of the connections is retrieved, where each connection is represented as one row with a unified and simplified geometry.

### 1. Sections
Request available public transport connections as detailed sections:
```{r pt_connection_section, eval = FALSE}
connection_section <- connection(
  origin = poi[3:4, ],
  destination = poi[5:6, ],
  summary = FALSE
)
```

The `id` column corresponds to the row of the input locations (`origin` and `destination`) and the `rank` column enumerates the alternative routes. The maximum number of alternatives can be set by the `results` parameter. Each row in the returned `sf` object corresponds to a route section with a transport mode in a vehicle without a transfer.

```{r table_connection_section, eval=TRUE, echo=FALSE, out.width='100%', fig.align='center', screenshot.force=FALSE}
knitr::kable(head(as.data.frame(connection_section)[, colnames(connection_section) != "geometry"]), format = "html")
```

Print the public transport sections on an interactive leaflet map:
```{r pt_connection_section_map, eval=TRUE, out.width='100%'}
mapview(connection_section,
        zcol = "mode",
        layer.name = "Transport mode",
        map.types = c("Esri.WorldTopoMap"),
        homebutton = FALSE
)
```

**Note:** The geometries of walking sections are straight lines between the origin, station or destination points instead of routed paths on the pedestrian network. The reason for this is that it is not possible to match the *"maneuvers"* to the *"connections-sections"* in the API response using the section id (`sec_id`). The walking segments can be routed in hindsight using the `route()` function with transport mode set to `"pedestrian"`.

### 2. Summary
Request a summary of the available public transport connections:
```{r pt_connection_summary, eval = FALSE}
connection_summary <- connection(
  origin = poi[3:4, ],
  destination = poi[5:6, ],
  summary = TRUE
)
```

```{r table_connection_summary, eval=TRUE, echo=FALSE, out.width='100%', fig.align='center', screenshot.force=FALSE}
knitr::kable(head(as.data.frame(connection_summary)[, colnames(connection_summary) != "geometry"]), format = "html")
```

## Stations
The function `station()` allows to request public transport stations nearby points of interest (POIs). The `radius` defines the maximum search distance in meters and `results` specifies the maximum number of returned stations. The returned `sf` object contains the locations of the stations and the available public transport lines at the station.

```{r stations, eval=FALSE}
stations <- station(
  poi = poi,
  radius = 500,
  results = 5
)
```

Print the POIs, the radius and stations on an interactive leaflet map:
```{r stations_map, eval=TRUE, out.width='100%'}
buffer <-
  poi %>%
  st_transform(2056) %>%
  st_buffer(500) %>%
  st_transform(4326)

m <-
  mapview(poi, alpha.region = 1, col.region = "black",
          label = poi$city, layer.name = "POIs",
          map.types = c("Esri.WorldTopoMap"), homebutton = FALSE) +
  mapview(stations, col.region = "yellow", alpha = 1,
          label = stations$station, layer.name = "Stations",
          homebutton = FALSE) +
  mapview(buffer, col.region = "transparent", alpha.region = 0,
          layer.name = "Buffer", homebutton = FALSE, legend = FALSE)
m
```

## API Reference

* [Transit Route](https://developer.here.com/documentation/transit/dev_guide/topics/quick-start-routing-1.html)
* [Find Stations Nearby](https://developer.here.com/documentation/examples/rest/public_transit/station-search-proximity)
