Overview

This guide explains how to use the API that exposes realtime location data for public transport in Chișinău. The highlights:

• It follows the publish-subscribe pattern
• MQTT is used for messaging
• Payloads are in JSON
• Vehicles send telemetry every ~3s
• Community support is available via chat

Why is this an open API?

Although the requirements for the public transport tracking system did not ask for it, someone went the extra mile to make it so. Public transport software is too important to be left in the hands of a single company. An open protocol enables others to roll out their own products that rely on the data - these can have more features, look nicer, or come up with innovative uses of the data that others have not thought of. Thus, consumers are less likely to end up using an outdated or abandoned application that does not keep up with progress.

Prerequisites

You will be more productive as you go through this guide, if you familiarize yourself with these first:

• Vehicle metadata, shared via vehicles.csv
• Route metadata, shared via routes.csv
• A basic understanding of the MQTT protocol

Technical overview

Every subscriber will receive the same data, as soon as a vehicle sends the information. You can have multiple subscriptions simultaneously, as well as run multiple instances of your clients.

                            +----------+
+----------+    publish     |          |
|  GPS     |   telemetry    |  MQTT    |
|  tracker +---------------->  broker  |
|          |                |          |
+----------+                |          |
                            |          |
                            +-+--+---+-+
                              |  |   |
            +-----------------+  |   |
            |                    |   +-------------+
            |                    |                 |
+-----------v-----+  +-----------v-----+     +-----v-------+
| MQTT subscriber |  |     Another     |     |     Yet     |
| (your software) |  | MQTT subscriber | ..  |   another   |
|                 |  |                 |     |    MQTT     |
|                 |  |                 |     | subscriber  |
+-----------------+  +-----------------+     +-------------+

A subscription requires a topic name, here are the ones you can use:

telemetry/transport/+

It distributes raw telemetry coming directly from each vehicle, the last element in the topic name will be the tracker ID. Refer to vehicles.csv to link the tracker ID to an actual vehicle.

For example, if the topic is telemetry/transport/000001, the tracker ID is 000001, it is attached to trolleybus 1273 (the transport company itself, e.g., RTEC, refers to this as a "board number").

All messages are JSON strings which contain the following keys:

Example:

{
    "longitude": 28.887143,
    "latitude": 47.026044,
    "timestamp": "2019-08-18T16:42:29Z",
    "speed": 0,
    "direction": 0.0
}

Warning:

The payloads may contain other, undocumented keys - don't count on them. However, treat this document like an RFC and keep in mind that you can argue for the inclusion of new attributes and modifications in the protocol.

telemetry/route/+

It distributes slightly enriched telemetry, grouped by route. The last element in the topic name is the route_upstream_id that you will find in routes.csv.

For example, if the topic is telemetry/route/1, the upstream route ID is 1, it corresponds to route 30, Aeroport - Piața Marii Adunări Naționale.

This is what the payloads look like:

Example:

{
    "latitude": 46.98579,
    "longitude": 28.857805,
    "timestamp": "2019-10-22T07:06:04Z",
    "speed": 12,
    "direction": 313.5,
    "board": "1308",
    "rtu_id": "0000019",
    "route": "3"
}

Note:

• If a vehicle is moved from one route to another, its telemetry will be automatically distributed via a topic that corresponds to the new route.
• You can subscribe to individual routes, by using their id in the topic name, e.g., telemetry/route/1.
• board, rtu_id and route are usually numerical values, but they can also contain letters, treat them as strings!

Warning:

The payloads may contain other, undocumented keys - don't count on them.

event/route/+

This topic disseminates information about recent changes related to a particular route, for example: a vehicle was taken off the route, or added to it. These details allow displays to be updated accordingly, to provide a smooth user experience. For example, if a vehicle was taken off a particular route, an application will mark it as such.

Example that shows what happens when board 1308, was removed from its current route:

{
    "event": "remove",
    "board": "1308",
    "rtu_id": "0000019",
}

Give it a try

You can use any MQTT client to subscribe to the topics above and see the live data. In these examples we shall use mosquitto_sub, distributed with the Mosquitto broker. On Debian-based systems you can install it with sudo apt install mosquitto-clients. Here's how to run it:

• mosquitto_sub -v -h opendata.dekart.com -p 1945 -t telemetry/transport/+ - receive raw telemetry
• mosquitto_sub -v -h opendata.dekart.com -p 1945 -t telemetry/route/+ - receive route-centric telemetry
• mosquitto_sub -v -h opendata.dekart.com -p 1945 -t event/route/+ - receive notifications when a vehicle was taken off a route

You can also try opendata.dekart.com:1946 for MQTT over plaintext websockets.

Credits

We thank Dekart for designing a system based on non-proprietary protocols and for opening it up to the public.

References

• MQTT libraries for different programming languages.
• Reference implementation that visualizes the vehicles on a map.