# Public Transit API

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:

    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.

id | rank | departure | origin | arrival | destination | mode | vehicle | direction | distance
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | 1 | 2020-03-29 20:54:00 | ORIG | 2020-03-29 21:04:00 | Lausanne, Sallaz | Walk | NA | NA | 582
1 | 1 | 2020-03-29 21:04:00 | Lausanne, Sallaz | 2020-03-29 21:13:00 | Lausanne, gare | Train | m2 | Lausanne, Ouchy-Olympique | 2974
1 | 1 | 2020-03-29 21:13:00 | Lausanne, gare | 2020-03-29 21:18:00 | Lausanne | Walk | NA | NA | 76
1 | 1 | 2020-03-29 21:20:00 | Lausanne | 2020-03-29 22:26:00 | Bern | Intercity Train | IC 1 | Zürich HB | 97091
1 | 1 | 2020-03-29 22:32:00 | Bern | 2020-03-29 22:43:00 | Kehrsatz Nord | Train | S 3 | Belp | 8668
1 | 1 | 2020-03-29 22:43:00 | Kehrsatz Nord | 2020-03-29 22:44:00 | DEST | Walk | NA | NA | 76

Print the public transport sections on an interactive leaflet map:

    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:

    connection_summary <- connection(
      origin = poi[3:4, ],
      destination = poi[5:6, ],
      summary = TRUE
    )

id | rank | departure | origin | arrival | destination | transfers | modes | vehicles | distance
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | 1 | 2020-03-29 20:54:00 | Lausanne, Sallaz | 2020-03-29 22:44:00 | Kehrsatz Nord | 2 | Train, Intercity Train, Train | m2, IC 1, S 3 | 109467
1 | 2 | 2020-03-29 21:18:00 | Lausanne, Sallaz | 2020-03-29 23:14:00 | Kehrsatz Nord | 2 | Train, Intercity Train, Train | m2, IR 15, S 3 | 109467
2 | 1 | 2020-03-29 20:26:00 | Basel, Kleinhüningen | 2020-03-29 22:19:00 | Zürich HB | 1 | Tram, Intercity Train | 8, 3 | 94432
2 | 2 | 2020-03-29 20:36:00 | Basel, Kleinhüningen | 2020-03-29 22:39:00 | Zürich HB | 1 | Tram, Intercity Train | 8, IR 36 | 94519

## 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.

    stations <- station(
      poi = poi,
      radius = 500,
      results = 5
    )

Print the POIs, the radius and stations on an interactive leaflet map:

    # NOTE: This code block is temporarily not evaluated due to an issue of the
    # mapview package when plotting multiple SF layers with the new CRS structure of
    # version 0.9-0 (see: https://github.com/r-spatial/mapview/issues/271).
    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
- Find Stations Nearby