Realtime

Realtime vehicle positions and stop sequences based on scheduled times and realtime updates.

The API is reachable at wss://api.geops.io/tracker-ws/v1/?key=<key> where <key> is your API key.

We also provide a client library using this API to display vehicles in a map.

To provide realtime updates we implemented a Websocket protocol using simple text commands to request data from the backend, which is delivered in (Geo)JSON.

EPSG:3857 "Web Mercator" is used for all coordinates, including in GeoJSON objects here.

Websocket API

This API is based on our redis-websocket-api.

Each response frame is wrapped in an envelope:

{
    "source":"<channel_name>|trajectory",
    "timestamp":<unix_timestamp_in_ms>,
    "client_reference":"None",
    "content": {...}
}

Vehicle Positions

The "source" is set to "trajectory" for vehicle positions.

To receive vehicle positions you need to specify a bounding box including a zoom level, optionally filtered by modes of transport, generalization, or data source (called tenant here):

BBOX <left> <bottom> <right> <top> <zoom>[ tenant=<tenant>][ gen=<generalization>][ mots=<mot1,mot2,...>]

• left bottom right top describe the extent of the bounding box in epsg:3857 coordinates

• zoom is the zoom level of the base map; lower means less detailed geometries and MOTs

• mots are the modes of transport, decided based on the zoom by default. Choices are:

  • tram
  • subway
  • rail
  • bus
  • ferry
  • cablecar
  • gondola
  • funicular
  • coach

• gen is relevant when using our public transport maps where we generalize based on the extent and zoom of the viewport. Choices are:

  • 5
  • 10
  • 30
  • 100

  Other values are also supported but fall back to one of the levels above or no generalization for out of range values.

• tenant can be used to limit results to one of the data sources

Trip Details

Other data requests use the geops/redis-websocket-api protocol, short summery of the commands:

GET <key> // fetches all data from a channel
GET <key> <id> // fetches a specific item from the channel
SUB <key> // subscribes the websocket to a channel to get event-based updates
DEL <key> // unsubscribes the client from the channel
PING // causes a PONG response (to avoid timeouts or validate the connection)

Full trajectory

Request the geometry for the complete trajectory by performing a

GET full_trajectory_<train_id>

where the train_id is taken from the vehicle position data.

Stop sequence

The stop sequence can be requested using

GET stopsequence_<train_id>

where the train_id is taken from the vehicle position data.