Docs

Introduction

The PONTOS project makes historical and (near) real-time ship operational data available to you, openly, through the PONTOS-HUB. Partners of the PONTOS project send their ships' operational data to PONTOS-HUB. Once received, the data is stored in an SQL database and is immediately made available through two APIs:

A REST API to provide access to historical data following a response/request model.
An MQTT API to provide access to (near) real-time data following a publish/subscribe model.

To use the APIs you will need an access token. To get an access token, visit the Get started page.

Keep in mind that the PONTOS-HUB is made available under the Open Database License (ODbL) v1.0 and that any rights in individual contents of the database are licensed under the Database Contents License (DbCL) v1.0.

Data format

The data in PONTOS-HUB consist of sensor data described with the following markers:

vessel_id: Identifying the vessel where the sensor data comes.
tag: Describing the type of sensor data.
index: Identifying the specific entity where the measurement was taken.

The following subsections describe these markers in more detail.

`vessel_id`

The vessel_id marker serves as a globally unique identifier for a vessel. It follows the format <type>_<value> where:

type: Describes the type of identifier.
value: Describes the value of the identifier.

There three possible values for type are:

name: Indicating that the identifier is the name of the vessel.
imo: Indicating that the identifier is the IMO number of the vessel.
mmsi: Indicating that the identifier is the MMSI number of the vessel.

For example, the following are valid vessel_id markers:

name_SD401Fredrika
imo_900711
mmsi_265585310

While the IMO number is the preferred method of identification, not all vessels possess one. In its absence, the MMSI number is used. If neither is available, the vessel's name becomes the identifier.

`tag`

The tag marker describes the type of measurement and adheres to the format <entity>_<property>_<unit>, where:

entity: Describes the type of entity where the measurement is taken.
property: Describes the property measured in the entity.
unit: Describes the units of the measurement.

For example, the following are valid tag markers:

propeller_speed_rpm
enginemain_power_kw

The first tag describes the measurement as the speed of a propeller in revolutions per minute (RPM), while the second one the power produced by a main engine in kilo Watts (kW).

To keep track of changes, the complete set of valid tags is not documented here, but in this Github repository.

Vessel descriptions

Currently, the PONTOS project does not provide descriptions of the vessels available in the PONTOS-HUB (e.g. length, breadth, installed power). Descriptions of the vessels can be found in the following sources through the IMO number, MMSI number or name stated in the vessel_id markers:

MQTT API

The MQTT API exposes (near) real-time operational data following a publish/subscribe model. You establish a connection to the MQTT broker, which acts as an intermediary between publishers and subscribers. Once connected, you can choose to subscribe to topics to receive updates. Notably, publishing rights are restricted, preventing the general public from broadcasting messages.

Take a look at this resource to learn more about MQTT protocol.

Connection details

The MQTT API is exposed through WebSockets with Transport Layer Security (TLS) (aka. Secure Websockets). To connect to the MQTT API use the following details:

Encryption (TLS): On
Protocol: ws:// (Or wss:// if TLS option is not available.)
Host: pontos.ri.se
Port: 443
Basepath: mqtt
Username: __token__
Password: <YOUR_ACCESS_TOKEN>
Topic: PONTOS_EGRESS/#

Topic structure

The MQTT topic follows this structure:

PONTOS_EGRESS/{vessel_id}/{tag}/{index}

For detailed descriptions of the markersvessel_id, tag, and index, refer to the Data format section.

Payload format

Payloads are structured in JSON as follows:

  {
    "timestamp: <Unix time when the measurement was taken [int|float]>,
    "value": <measured value [int|float|string]>
  }

Broker configuration

Here are some details of the configuration of the MQTT broker:

Only Quality Of Service (QoS) equal to 0 is supported.
Data publishers are free to send retained data at their will, but subscribers should not rely on it.
There are no rate limits for subscribers, only for publishers.
All MQTT protocol versions are supported, but v5 is preferred.

Examples

REST API

The RESTful API provides access to historical data following a response/request model. You make a request to a specific endpoint, specifying the desired data parameters, and the server processes this request. Once processed, the server sends back a response containing the requested data or an appropriate error message if the data cannot be retrieved. This interaction is based on standard HTTP methods, ensuring compatibility and ease of integration with various platforms and tools.

The REST API is provided by PostgREST. As such, the queries for selecting, filtering, limiting and otherwise handling the data in the REST API must follow the query syntax described here.

📌 The REST API has a hard limit of maximum 1 000 000 rows for any single request.

Resources

Currently, the REST API supports read-only access to 7 resources:

vessel_ids: Containing the distinct vessel_id markers of all the available vessels.
vessel_data: Containing the historical operational data of all the vessels.
vessel_data_5_seconds_average: The data of vessel_data but averaged in time buckets of 5 seconds.
vessel_data_30_seconds_average: The data of vessel_data but averaged in time buckets of 30 seconds.
vessel_data_1_minute_average: The data of vessel_data but averaged in time buckets of 1 minute.
vessel_data_5_minutes_average: The data of vessel_data but averaged in time buckets of 5 minutes.
vessel_data_10_minutes_average: The data of vessel_data but averaged in time buckets of 10 minutes.

In the vessel_data resource, the operational data is stored in the following format:

time (TIMESTAMPZ)   |   vessel_id (TEXT)   |   parameter_id (TEXT)   |   value (TEXT)

where:

time: Indicates the time when the measurment was taken in UTC.
vessel_id: Refer to Data format for detailed information.
parameter_id: Identifies the measurement by combining the tag and index markers as follows <tag>_<index>. More details can be found in Data format.
value: Denotes value of the measurement.

📌 It is important to note that in this API value is of type TEXT. This greatly enhances the flexibility of the data hub but also means that casting this column to the type that is suitable/expected by the end-user is the recommended way of working.

For the vessel_data_X_X_averaged resources, for each measurement the returned fields are:

bucket: The start time of the bucket (see timescaledb docs).
vessel_id: Refer to Data format for detailed information.
parameter_id: Identifies the measurement by combining the tag and index markers as follows <tag>_<index>. More details can be found in Data format.
avg_time: The average timestamp in UTC of all the measurements in the bucket.
avg_value: The aveage value of all the measurments in the bucket. The value is returned as a FLOAT.

Endpoints

Currently, the REST API has two URL endpoints corresponding to the two available resources:

https://pontos.ri.se/api/vessel_ids
https://pontos.ri.se/api/vessel_data

Queries

In the REST API, a "query" refers to the use of query parameters in the URL endpoint to filter, sort, paginate, or provide additional information about how the server should process the request. These parameters are appended to the URL after a ? character and are usually in the form of key-value pairs separated by &. Refer to the PostgREST documentation for detailed information.

Examples

The examples here show how to perform requests to the REST API in the terminal or command window with curl. Additional examples can be found here.

Get data from the `vessel_ids` resource

Since the vessel_ids resource has simple structure and does not contain a large amount of data, a simple request without any query parameters can be effectively used to obtain the desired information.

curl -X GET \
     -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
     'https://pontos.ri.se/api/vessel_ids'

Get the data from the `vessel_data` resource

In contrast with vessel_ids, the vessel_data resource has a more complex structure and contains a large amount of data. For example, a full day for a single vessel is ~50 MB of data. The example below request the data of a specific vessel (vessel_id = imo_9007128), within a specific time span (2023-10-29 -> 2023-10-30), and limiting the output to 100 entries.

curl -X GET \
     -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
     'https://pontos.ri.se/api/vessel_data?vessel_id=eq.imo_9007128&time=gte.2023-10-29&time=lt.2023-10-30&limit=100'

Additional documentation

The code of PONTOS-HUB is open-source. Check out the Github repository to take a look at the code and read the more in-depth documentation of how PONTOS-HUB works.

PONTOS

Driven by

Financed by

Github

pontos-hub(a)ri.se

Docs

Contents

Introduction

Data format

vessel_id

tag

Vessel descriptions

MQTT API

Connection details

Topic structure

Payload format

Broker configuration

Examples

REST API

Resources

Endpoints

Queries

Examples

Get data from the vessel_ids resource

Get the data from the vessel_data resource

Additional documentation

PONTOS

`vessel_id`

`tag`

Get data from the `vessel_ids` resource

Get the data from the `vessel_data` resource