roataway / api-documentation

Roatawăy API documentation for 3rd-party integrators
21 stars 1 forks source link
chisinau moldova open-data public-transport

Overview

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

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:

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:

Field Type Notes
latitude float
longitude float
direction float
speed int In km/h
timestamp str In UTC, e.g. 2019-08-18T16:42:29Z the format is %Y-%m-%dT%H:%M:%SZ

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:

Field Type Notes
latitude float
longitude float
direction float
speed int In km/h
timestamp str In UTC, e.g. 2019-08-18T16:42:29Z the format is %Y-%m-%dT%H:%M:%SZ
board str The board number of the vehicle
rtu_id str The tracker ID
route str The route name (not to be confused with route_upstream_id!)

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:

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.

Field Type Notes
event str Only remove events are considered, new ones might be added later.
board str The board number of the vehicle
rtu_id str The tracker ID

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:

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