---
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(sf)

if (requireNamespace("mapview", quietly = TRUE)) {
  mapview::mapviewOptions(
    fgb = FALSE,
    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=FALSE, out.width='100%'}
if (requireNamespace("mapview", quietly = TRUE)) {
  mapview::mapview(connection_section,
    zcol = "mode",
    layer.name = "Transport mode",
    map.types = c("Esri.WorldTopoMap"),
    homebutton = FALSE
  )
}
```

### 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=FALSE, out.width='100%'}
buffer <-
  poi %>%
  st_transform(2056) %>%
  st_buffer(500) %>%
  st_transform(4326)

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

## API Reference

- [Public Transit Routing API](https://www.here.com/docs/bundle/public-transit-api-developer-guide/page/README.html)