Voyage Events API can be used to subscribe to real-time events related to sea voyages. Currently, the API supports zone events, which are sent when a ship has arrived to or departed from a given area (zone) defined by a geo-fence.
The API is based on WebSockets. Communication with the API starts by the client sending a subscription request message, including a description of the type of events it wishes to subscribe to. In the below example, the client subscribes to events for zones located in Finland (FI). Additionally, it is also possible to subscribe to zones associated with certain locodes.
{"msgType": "subscribe", "parameters": [{"eventType": "zone-event", "countries": ["FI"]}]}
The API will then respond with a subscription status message, signaling if the subscription was
successful or not. If the subscription was successful, the server will respond with status ok
and a unique subscription ID:
{"msgType": "subscription-status", "status": "ok", "subscriptionId": "f0823c69-7c67-4851-8d97-a525445a8b38"}
Following this, the API will start sending events. A typical zone event looks like the following:
{
"msgType": "event",
"eventType": "zone-event",
"eventTimestamp": "2021-10-18T12:25:37+00:00",
"eventId": "daf3e03d-6cd1-4624-be03-5d799b006789",
"mmsi": 248562000,
"imo": 9457191,
"shipName": "EUROCARGO SAVONA",
"location": [59.762187, 23.021522],
"zoneId": "8fbfc1f1-cab1-4414-8cd0-d36121afd4ec",
"zoneType": "pbp",
"zoneEventType": "departure",
"zoneName": "Hanko N",
"locodes": ["FIHKO"]
}
If the websocket is disconnected, the client can resume the session with the subscription ID received in the subscription status message as follows:
{"msgType": "subscribe", "resume": "f0823c69-7c67-4851-8d97-a525445a8b38"}
If the provided subscription ID is recognized by the server, the client will receive an equivalent subscription status message as above. When a subscription is resumed, the server will first send possible events that happened while the client was disconnected, before starting to send real-time events.
The service requires authentication with a token passed as a query parameter. The token is provided by Awake.AI.
Example:
https://voyages-api.prod.awake.ai/v1/ws?token=<api key>
The service requires authentication with a token passed as a query parameter. The token is provided by Awake.AI.
Example:
https://voyages-api.stage.awake.ai/v1/ws?token=<api key>
The service requires authentication with a token passed as a query parameter. The token is provided by Awake.AI.
Example:
https://voyages-api.dev.awake.ai/v1/ws?token=<api key>
Send messages to the API
Accepts the following message:
Subscription request sent by the client, specifying the events to subscribe to
{
"msgType": "subscribe",
"parameters": [
{
"eventType": "zone-event",
"countries": [
"FI"
]
}
]
}
{
"msgType": "subscribe",
"parameters": [
{
"eventType": "zone-event",
"locodes": [
"FIRAU",
"FIKOK"
]
}
]
}
{
"msgType": "subscribe",
"resume": "f0823c69-7c67-4851-8d97-a525445a8b38"
}
Receive message from the API
Accepts one of the following messages:
Subscription status provided by the server as a response to a subscription request
{
"msgType": "subscription-status",
"status": "ok",
"subscriptionId": "f0823c69-7c67-4851-8d97-a525445a8b38"
}
{
"msgType": "subscription-status",
"status": "failed",
"message": "Unknown subscriptionId"
}
Zone events delivered by the server
{
"msgType": "event",
"eventType": "zone-event",
"eventTimestamp": "2021-09-14T06:45:20+00:00",
"eventId": "f0823c69-7c67-4851-8d97-a525445a8b38",
"mmsi": 248562000,
"imo": 9457191,
"shipName": "EUROCARGO SAVONA",
"location": [
59.762187,
23.021522
],
"zoneId": "e2f00ff0-3c4f-4e8d-a887-5c1dba38ca15",
"zoneType": "pbp",
"zoneEventType": "arrival",
"zoneName": "Rauma S",
"locodes": [
"FIRAU"
]
}
Subscription request sent by the client, specifying the events to subscribe to
Subscription status provided by the server as a response to a subscription request
Zone events delivered by the server
Zone event subscription request
Successful subscription status
Failed subscription status