Skip to content

Mapbox Vector Tiles API

Contact Info

  • HSL, Finland
  • Arcadis, US

Documentation

This API produces Mapbox vector tiles, which are used by Digitransit-ui and otp-react-redux to show information about public transit entities on the map.

The tiles can be fetched from /otp/routers/{routerId}/vectorTiles/{layers}/{z}/{x}/{y}.pbf, where layers is a comma separated list of layer names from the configuration.

Maplibre/Mapbox GL JS also requires a tilejson.json endpoint which is available at /otp/routers/{routerId}/vectorTiles/{layers}/tilejson.json.

Translatable fields in the tiles are translated based on the accept-language header in requests. Currently, only the language with the highest priority from the header is used.

Configuration

To enable this you need to add the feature otp-config.json.

// otp-config.json
{
  "otpFeatures": {
    "SandboxAPIMapboxVectorTilesApi": true
  }
}

The feature must be configured in router-config.json as follows

{
  "vectorTiles": {
    "basePath": "/only/configure/if/required",
    "layers": [
      {
        "name": "stops",
        "type": "Stop",
        "mapper": "Digitransit",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 600
      },
      // flex zones
      {
        "name": "areaStops",
        "type": "AreaStop",
        "mapper": "OTPRR",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 600
      },
      {
        "name": "stations",
        "type": "Station",
        "mapper": "Digitransit",
        "maxZoom": 20,
        "minZoom": 12,
        "cacheMaxSeconds": 600
      },
      // all rental places: stations and free-floating vehicles
      {
        "name": "citybikes",
        "type": "VehicleRental",
        "mapper": "Digitransit",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 60,
        "expansionFactor": 0.25
      },
      // just free-floating vehicles
      {
        "name": "rentalVehicles",
        "type": "VehicleRentalVehicle",
        "mapper": "DigitransitRealtime",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 60
      },
      // just rental stations
      {
        "name": "rentalStations",
        "type": "VehicleRentalStation",
        "mapper": "Digitransit",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 600
      },
      // Contains just stations and real-time information for them
      {
        "name": "realtimeRentalStations",
        "type": "VehicleRentalStation",
        "mapper": "DigitransitRealtime",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 60
      },
      // Contains just stops and real-time information for them
      {
        "name": "realtimeStops",
        "type": "Stop",
        "mapper": "DigitransitRealtime",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 60
      },
      // This exists for backwards compatibility. At some point, we might want
      // to add a new real-time parking mapper with better translation support
      // and less unnecessary fields.
      {
        "name": "stadtnaviVehicleParking",
        "type": "VehicleParking",
        "mapper": "Stadtnavi",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 60,
        "expansionFactor": 0.25
      },
      // no real-time, translatable fields are translated based on accept-language header
      // and contains less fields than the Stadtnavi mapper
      {
        "name": "vehicleParking",
        "type": "VehicleParking",
        "mapper": "Digitransit",
        "maxZoom": 20,
        "minZoom": 14,
        "cacheMaxSeconds": 600,
        "expansionFactor": 0.25
      },
      {
        "name": "vehicleParkingGroups",
        "type": "VehicleParkingGroup",
        "mapper": "Digitransit",
        "maxZoom": 17,
        "minZoom": 14,
        "cacheMaxSeconds": 600,
        "expansionFactor": 0.25
      }
    ] 
  }
}

For each layer, the configuration includes:

  • name which is used in the url to fetch tiles, and as the layer name in the vector tiles.
  • type which tells the type of the layer. Currently supported:
    • Stop
    • AreaStop: Flex zones
    • Station
    • VehicleRental: all rental places: stations and free-floating vehicles
    • VehicleRentalVehicle: free-floating rental vehicles
    • VehicleRentalStation: rental stations
    • VehicleParking
    • VehicleParkingGroup
Config Parameter Type Summary Req./Opt. Default Value Since
attribution string Custom attribution to be returned in tilejson.json Optional 2.5
basePath string The path of the vector tile source URLs in tilejson.json. Optional 2.5
layers object[] Configuration of the individual layers for the Mapbox vector tiles. Optional 2.0
      type = "stop" enum Type of the layer. Required 2.0
      cacheMaxSeconds integer Sets the cache header in the response. Optional -1 2.0
      expansionFactor double How far outside its boundaries should the tile contain information. Optional 0.25 2.0
      filter enum Reduce the result set of a layer further by a specific filter. Optional "none" 2.6
      mapper string Describes the mapper converting from the OTP model entities to the vector tile properties. Required 2.0
      maxZoom integer Maximum zoom levels the layer is active for. Optional 20 2.0
      minZoom integer Minimum zoom levels the layer is active for. Optional 9 2.0
      name string Used in the url to fetch tiles, and as the layer name in the vector tiles. Required 2.0

Details

attribution

Since version: 2.5 ∙ Type: string ∙ Cardinality: Optional
Path: /vectorTiles

Custom attribution to be returned in tilejson.json

By default the, attribution property in tilejson.json is computed from the names and URLs of the feed publishers. If the OTP deployment contains many feeds, this can become very unwieldy.

This configuration parameter allows you to set the attribution to any string you wish including HTML tags, for example <a href='https://trimet.org/mod'>Regional Partners</a>.

basePath

Since version: 2.5 ∙ Type: string ∙ Cardinality: Optional
Path: /vectorTiles

The path of the vector tile source URLs in tilejson.json.

This is useful if you have a proxy setup and rewrite the path that is passed to OTP.

If you don't configure this optional value then the path returned in tilejson.json is in the format /otp/routers/default/vectorTiles/layer1,layer2/{z}/{x}/{x}.pbf. If you, for example, set a value of /otp_test/tiles then the returned path changes to /otp_test/tiles/layer1,layer2/{z}/{x}/{x}.pbf.

The protocol and host are always read from the incoming HTTP request. If you run OTP behind a proxy then make sure to set the headers X-Forwarded-Proto and X-Forwarded-Host to make OTP return the protocol and host for the original request and not the proxied one.

Note: This does not change the path that OTP itself serves the tiles or tilejson.json responses but simply changes the URLs listed in tilejson.json. The rewriting of the path is expected to be handled by a proxy.

layers

Since version: 2.0 ∙ Type: object[] ∙ Cardinality: Optional
Path: /vectorTiles

Configuration of the individual layers for the Mapbox vector tiles.

cacheMaxSeconds

Since version: 2.0 ∙ Type: integer ∙ Cardinality: Optional ∙ Default value: -1
Path: /vectorTiles/layers/[0]

Sets the cache header in the response.

The lowest value of the layers included is selected.

expansionFactor

Since version: 2.0 ∙ Type: double ∙ Cardinality: Optional ∙ Default value: 0.25
Path: /vectorTiles/layers/[0]

How far outside its boundaries should the tile contain information.

The value is a fraction of the tile size. If you are having problem with icons and shapes being clipped at tile edges, then increase this number.

filter

Since version: 2.6 ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "none"
Path: /vectorTiles/layers/[0]
Enum values: none | sunday-to-sunday-service-week

Reduce the result set of a layer further by a specific filter.

This is useful for when the schema of a layer, say stops, should remain unchanged but some elements should not be included in the result.

mapper

Since version: 2.0 ∙ Type: string ∙ Cardinality: Required
Path: /vectorTiles/layers/[0]

Describes the mapper converting from the OTP model entities to the vector tile properties.

Currently Digitransit is supported for all layer types.

Extending

If more generic layers are created for this API, the code should be moved out from the sandbox, into the core, perhaps potentially leaving specific property mappers in place.

Creating a new layer

In order to create a new type of layer, you need to create a new class extending LayerBuilder<T>. You need to implement two methods, List<Geometry> getGeometries(Envelope query), which returns a list of geometries, with an object of type T as their userData in the geometry, and double getExpansionFactor(), which describes how much information outside the tile bounds should be included. This layer then needs to be added into VectorTilesResource.layers, with a new LayerType enum as the key, and the class constructor as the value.

A new mapper needs to be added every time a new layer is added. See below for information.

Creating a new mapper

The mapping contains information of what data to include in the vector tiles. The mappers are defined per layer.

In order to create a new mapper for a layer, you need to create a new class extending PropertyMapper<T>. In that class, you need to implement the method Collection<KeyValue<String, Object>> map(T input). The type T is dependent on the layer for which you implement the mapper for. It needs to return a list of attributes, as key-value pairs which will be written into the vector tile.

The mapper needs to be added to the mappers map in the layer, with a new MapperType enum as the key, and a function to create the mapper, with a Graph object as a parameter, as the value.

Changelog

  • 2020-07-09: Initial version of Mapbox vector tiles API
  • 2021-05-12: Make expansion factor configurable
  • 2021-09-07: Rename BikeRental to VehicleRental
  • 2021-10-13: Correctly serialize the vehicle rental name #3648
  • 2022-01-03: Add support for VehicleParking entities
  • 2022-04-27: Read the headsign for frequency-only patterns correctly #4122
  • 2022-08-23: Remove patterns and add route gtfsTypes to stop layer #4404
  • 2022-10-11: Added layer for VehicleParkingGroups #4510
  • 2022-10-14: Add separate layers for vehicle rental place types #4516
  • 2022-10-19 #4529:
  • Translatable fields are now translated based on accept-language header
  • Added DigitransitRealtime for vehicle rental stations
  • Changed old vehicle parking mapper to be Stadtnavi
  • Added a new Digitransit vehicle parking mapper with no real-time information and less fields
  • 2024-01-22: Make basePath configurable #5627
  • 2024-02-27: Add layer for flex zones #5704
  • 2024-03-25: Add layer for realtime stops #5743