# 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 | section | departure | origin | arrival | destination | mode | category | vehicle | provider | direction | distance | duration
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | 1 | 1 | 2023-09-18 14:48:00 | ORIG | 2023-09-18 14:52:00 | Lausanne, Vallonnette | pedestrian | NA | NA | NA | NA | 211 | 240
1 | 1 | 2 | 2023-09-18 14:52:00 | Lausanne, Vallonnette | 2023-09-18 15:01:00 | Lausanne, St-François | bus | Bus Service | 6 | Transports Publics de la Région Lausannoise sa | Lausanne, Montoie | 3218 | 540
1 | 1 | 3 | 2023-09-18 15:03:00 | Lausanne, St-François | 2023-09-18 15:07:00 | Lausanne, Closelet | bus | Bus Service | 2 | Transports Publics de la Région Lausannoise sa | Lausanne, Maladière-Lac | 1003 | 240
1 | 1 | 4 | 2023-09-18 15:07:00 | Lausanne, Closelet | 2023-09-18 15:12:00 | Lausanne | pedestrian | NA | NA | NA | NA | 300 | 300
1 | 1 | 5 | 2023-09-18 15:13:00 | Lausanne | 2023-09-18 16:27:00 | Bern | intercityTrain | Long Distance Trains | IC1 | Schweizerische Bundesbahnen SBB | St. Gallen | 97030 | 4440
1 | 1 | 6 | 2023-09-18 16:32:00 | Bern | 2023-09-18 16:43:00 | Kehrsatz Nord | cityTrain | Suburban Railway | S3 | BLS AG (bls) | Belp | 8686 | 660

Print the public transport sections on an interactive leaflet map:

    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:

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

id | rank | departure | origin | arrival | destination | transfers | modes | categories | vehicles | providers | distance | duration
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
1 | 1 | 2023-09-18 14:48:00 | Lausanne, Vallonnette | 2023-09-18 16:46:00 | Kehrsatz Nord | 3 | pedestrian, bus, bus, pedestrian, intercityTrain, cityTrain, pedestrian | Bus Service, Bus Service, Long Distance Trains, Suburban Railway | 6, 2, IC1, S3 | Transports Publics de la Région Lausannoise sa, Transports Publics de la Région Lausannoise sa, Schweizerische Bundesbahnen SBB, BLS AG (bls) | 110651 | 6600
1 | 2 | 2023-09-18 14:54:00 | Lausanne, Georgette | 2023-09-18 17:40:00 | Wabern, Kleinwabern | 3 | pedestrian, bus, pedestrian, intercityTrain, cityTrain, pedestrian, bus, pedestrian | Bus Service, Inter Regional Rail Service, Suburban Railway, Bus Service | 1, IR15, S3, 22 | Transports Publics de la Région Lausannoise sa, Schweizerische Bundesbahnen SBB, BLS AG (bls), Städtische Verkehrsbetriebe Bern | 109116 | 9180
2 | 1 | 2023-09-18 15:00:00 | Kleinhüningen | 2023-09-18 16:41:00 | Zürich HB | 1 | pedestrian, lightRail, pedestrian, highSpeedTrain, pedestrian | Tram Service, High Speed Rail Service | 8, TGV TGV | Basler Verkehrsbetriebe, Schweizerische Bundesbahnen SBB | 97006 | 5880
2 | 2 | 2023-09-18 15:02:00 | Kleinhüningen | 2023-09-18 16:41:00 | Zürich HB | 2 | pedestrian, bus, pedestrian, cityTrain, highSpeedTrain, pedestrian | Bus Service, Suburban Railway, High Speed Rail Service | 46, S6, TGV TGV | Basler Verkehrsbetriebe, SBB GmbH (Grenzverkehr), Schweizerische Bundesbahnen SBB | 96896 | 5460

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

    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