|
| 1 | +# Mapbox Vector Tiles API |
| 2 | + |
| 3 | +## Contact Info |
| 4 | + |
| 5 | +- HSL, Finland |
| 6 | +- Arcadis, US |
| 7 | + |
| 8 | +## Documentation |
| 9 | + |
| 10 | +This API produces [Mapbox vector tiles](https://docs.mapbox.com/vector-tiles/reference/), which are |
| 11 | +used by [Digitransit-ui](https://github.com/HSLdevcom/digitransit-ui) and |
| 12 | +[`otp-react-redux`](https://github.com/opentripplanner/otp-react-redux) to show information about |
| 13 | +public transit entities on the map. |
| 14 | + |
| 15 | +The tiles can be fetched from `/otp/routers/{routerId}/vectorTiles/{layers}/{z}/{x}/{y}.pbf`, |
| 16 | +where `layers` is a comma separated list of layer names from the configuration. |
| 17 | + |
| 18 | +Maplibre/Mapbox GL JS also requires a tilejson.json endpoint which is available at |
| 19 | +`/otp/routers/{routerId}/vectorTiles/{layers}/tilejson.json`. |
| 20 | + |
| 21 | +Translatable fields in the tiles are translated based on the `accept-language` header in requests. |
| 22 | +Currently, only the language with the highest priority from the header is used. |
| 23 | + |
| 24 | +### Configuration |
| 25 | + |
| 26 | +To enable this you need to add the feature `otp-config.json`. |
| 27 | + |
| 28 | +```json |
| 29 | +// otp-config.json |
| 30 | +{ |
| 31 | + "otpFeatures": { |
| 32 | + "SandboxAPIMapboxVectorTilesApi": true |
| 33 | + } |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +The feature must be configured in `router-config.json` as follows |
| 38 | + |
| 39 | +```JSON |
| 40 | +{ |
| 41 | + "vectorTiles": { |
| 42 | + "basePath": "/only/configure/if/required", |
| 43 | + "layers": [ |
| 44 | + { |
| 45 | + "name": "stops", |
| 46 | + "type": "Stop", |
| 47 | + "mapper": "Digitransit", |
| 48 | + "maxZoom": 20, |
| 49 | + "minZoom": 14, |
| 50 | + "cacheMaxSeconds": 600 |
| 51 | + }, |
| 52 | + { |
| 53 | + "name": "stations", |
| 54 | + "type": "Station", |
| 55 | + "mapper": "Digitransit", |
| 56 | + "maxZoom": 20, |
| 57 | + "minZoom": 12, |
| 58 | + "cacheMaxSeconds": 600 |
| 59 | + }, |
| 60 | + // all rental places: stations and free-floating vehicles |
| 61 | + { |
| 62 | + "name": "citybikes", |
| 63 | + "type": "VehicleRental", |
| 64 | + "mapper": "Digitransit", |
| 65 | + "maxZoom": 20, |
| 66 | + "minZoom": 14, |
| 67 | + "cacheMaxSeconds": 60, |
| 68 | + "expansionFactor": 0.25 |
| 69 | + }, |
| 70 | + // just free-floating vehicles |
| 71 | + { |
| 72 | + "name": "rentalVehicles", |
| 73 | + "type": "VehicleRentalVehicle", |
| 74 | + "mapper": "DigitransitRealtime", |
| 75 | + "maxZoom": 20, |
| 76 | + "minZoom": 14, |
| 77 | + "cacheMaxSeconds": 60 |
| 78 | + }, |
| 79 | + // just rental stations |
| 80 | + { |
| 81 | + "name": "rentalStations", |
| 82 | + "type": "VehicleRentalStation", |
| 83 | + "mapper": "Digitransit", |
| 84 | + "maxZoom": 20, |
| 85 | + "minZoom": 14, |
| 86 | + "cacheMaxSeconds": 600 |
| 87 | + }, |
| 88 | + // Contains just stations and real-time information for them |
| 89 | + { |
| 90 | + "name": "realtimeRentalStations", |
| 91 | + "type": "VehicleRentalStation", |
| 92 | + "mapper": "DigitransitRealtime", |
| 93 | + "maxZoom": 20, |
| 94 | + "minZoom": 14, |
| 95 | + "cacheMaxSeconds": 60 |
| 96 | + }, |
| 97 | + // This exists for backwards compatibility. At some point, we might want |
| 98 | + // to add a new real-time parking mapper with better translation support |
| 99 | + // and less unnecessary fields. |
| 100 | + { |
| 101 | + "name": "stadtnaviVehicleParking", |
| 102 | + "type": "VehicleParking", |
| 103 | + "mapper": "Stadtnavi", |
| 104 | + "maxZoom": 20, |
| 105 | + "minZoom": 14, |
| 106 | + "cacheMaxSeconds": 60, |
| 107 | + "expansionFactor": 0.25 |
| 108 | + }, |
| 109 | + // no real-time, translatable fields are translated based on accept-language header |
| 110 | + // and contains less fields than the Stadtnavi mapper |
| 111 | + { |
| 112 | + "name": "vehicleParking", |
| 113 | + "type": "VehicleParking", |
| 114 | + "mapper": "Digitransit", |
| 115 | + "maxZoom": 20, |
| 116 | + "minZoom": 14, |
| 117 | + "cacheMaxSeconds": 600, |
| 118 | + "expansionFactor": 0.25 |
| 119 | + }, |
| 120 | + { |
| 121 | + "name": "vehicleParkingGroups", |
| 122 | + "type": "VehicleParkingGroup", |
| 123 | + "mapper": "Digitransit", |
| 124 | + "maxZoom": 17, |
| 125 | + "minZoom": 14, |
| 126 | + "cacheMaxSeconds": 600, |
| 127 | + "expansionFactor": 0.25 |
| 128 | + } |
| 129 | + ] |
| 130 | + } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +For each layer, the configuration includes: |
| 135 | + |
| 136 | +- `name` which is used in the url to fetch tiles, and as the layer name in the vector tiles. |
| 137 | +- `type` which tells the type of the layer. Currently supported: |
| 138 | + - `Stop` |
| 139 | + - `Station` |
| 140 | + - `VehicleRental`: all rental places: stations and free-floating vehicles |
| 141 | + - `VehicleRentalVehicle`: free-floating rental vehicles |
| 142 | + - `VehicleRentalStation`: rental stations |
| 143 | + - `VehicleParking` |
| 144 | + - `VehicleParkingGroup` |
| 145 | + |
| 146 | +<!-- INSERT: parameters --> |
| 147 | + |
| 148 | +### Extending |
| 149 | + |
| 150 | +If more generic layers are created for this API, the code should be moved out from the sandbox, into |
| 151 | +the core, perhaps potentially leaving specific property mappers in place. |
| 152 | + |
| 153 | +#### Creating a new layer |
| 154 | + |
| 155 | +In order to create a new type of layer, you need to create a new class extending `LayerBuilder<T>`. |
| 156 | +You need to implement two methods, `List<Geometry> getGeometries(Envelope query)`, which returns a |
| 157 | +list of geometries, with an object of type `T` as their userData in the geometry, |
| 158 | +and `double getExpansionFactor()`, which describes how much information outside the tile bounds |
| 159 | +should be included. This layer then needs to be added into `VectorTilesResource.layers`, with a |
| 160 | +new `LayerType` enum as the key, and the class constructor as the value. |
| 161 | + |
| 162 | +A new mapper needs to be added every time a new layer is added. See below for information. |
| 163 | + |
| 164 | +#### Creating a new mapper |
| 165 | + |
| 166 | +The mapping contains information of what data to include in the vector tiles. The mappers are |
| 167 | +defined per layer. |
| 168 | + |
| 169 | +In order to create a new mapper for a layer, you need to create a new class |
| 170 | +extending `PropertyMapper<T>`. In that class, you need to implement the |
| 171 | +method `Collection<KeyValue<String, Object>> map(T input)`. The type T is dependent on the layer for which |
| 172 | +you implement the mapper for. It needs to return a list of attributes, as key-value pairs which will |
| 173 | +be written into the vector tile. |
| 174 | + |
| 175 | +The mapper needs to be added to the `mappers` map in the layer, with a new `MapperType` enum as the |
| 176 | +key, and a function to create the mapper, with a `Graph` object as a parameter, as the value. |
| 177 | + |
| 178 | +## Changelog |
| 179 | + |
| 180 | +- 2020-07-09: Initial version of Mapbox vector tiles API |
| 181 | +- 2021-05-12: Make expansion factor configurable |
| 182 | +- 2021-09-07: Rename `BikeRental` to `VehicleRental` |
| 183 | +- 2021-10-13: Correctly serialize the vehicle rental name [#3648](https://github.com/opentripplanner/OpenTripPlanner/pull/3648) |
| 184 | +- 2022-01-03: Add support for VehicleParking entities |
| 185 | +- 2022-04-27: Read the headsign for frequency-only patterns correctly [#4122](https://github.com/opentripplanner/OpenTripPlanner/pull/4122) |
| 186 | +- 2022-08-23: Remove patterns and add route gtfsTypes to stop layer [#4404](https://github.com/opentripplanner/OpenTripPlanner/pull/4404) |
| 187 | +- 2022-10-11: Added layer for VehicleParkingGroups [#4510](https://github.com/opentripplanner/OpenTripPlanner/pull/4510) |
| 188 | +- 2022-10-14: Add separate layers for vehicle rental place types [#4516](https://github.com/opentripplanner/OpenTripPlanner/pull/4516) |
| 189 | +- 2022-10-19 [#4529](https://github.com/opentripplanner/OpenTripPlanner/pull/4529): |
| 190 | + * Translatable fields are now translated based on accept-language header |
| 191 | + * Added DigitransitRealtime for vehicle rental stations |
| 192 | + * Changed old vehicle parking mapper to be Stadtnavi |
| 193 | + * Added a new Digitransit vehicle parking mapper with no real-time information and less fields |
| 194 | +- 2024-01-22: Make `basePath` configurable [#5627](https://github.com/opentripplanner/OpenTripPlanner/pull/5627) |
0 commit comments