Awake.AI Voyage Events API 1.0.0 documentation

Awake.AI Voyage Events API 1.0.0

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.

Servers

voyages-api.prod.awake.ai/v1/wswssprod
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>
voyages-api.stage.awake.ai/v1/wswssstage
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>
voyages-api.dev.awake.ai/v1/wswssdev
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>

Operations

RECEIVE /
Send messages to the API

Operation IDprocessReceivedMessage
Available only on servers:
Accepts the following message:
Message IDSubscriptionRequest
Subscription request sent by the client, specifying the events to subscribe to

object
>= 2 properties
msgType
required
string
Const:"subscribe"
array<oneOf>
Specify events to subscribe to

Items:
oneOf
object
Zone event subscription request

eventType
required
string
Type of events to subscribe to

Const:"zone-event"
array<string>
Items:
string
must match: ^[A-Z]{5}$
UN/LOCODE of a port

array<string>
Items:
string
must match: ^[A-Z]{2}$
Two letter country code, i.e. two first letters of a UN/LOCODE

Additional properties are allowed.
resume
string
format: uuid
Additional properties are allowed.
tuple<object, ...optional<any>>
1 item:
object
description
Subscription status provided by the server as a response to a subscription request
object oneOf
msgType
string
Const:"subscription-status"
object
Successful subscription status

status
string
Const:"ok"
subscriptionId
string
format: uuid
ID of the started subscription

Additional properties are allowed.
object
Failed subscription status

status
string
Const:"failed"
message
string
Error message describing why the subscription failed

Additional properties are allowed.
Additional properties are allowed.
tuple<object, object, ...optional<any>>
1 item:
object
object
msgType
subscription-status
status
ok
subscriptionId
f0823c69-7c67-4851-8d97-a525445a8b38
2 item:
object
object
msgType
subscription-status
status
failed
message
Unknown subscriptionId
Examples
#1 Example
{ "msgType": "subscribe", "parameters": [ { "eventType": "zone-event", "countries": [ "FI" ] } ] }

#2 Example
{ "msgType": "subscribe", "parameters": [ { "eventType": "zone-event", "locodes": [ "FIRAU", "FIKOK" ] } ] }

#3 Example
{ "msgType": "subscribe", "resume": "f0823c69-7c67-4851-8d97-a525445a8b38" }
SEND /
Receive message from the API

Operation IDsendMessage
Available only on servers:
Accepts one of the following messages:
- #0
  Message IDSubscriptionStatus
  Subscription status provided by the server as a response to a subscription request
  
  object oneOf
  msgType
  string
  Const:"subscription-status"
  object
  Successful subscription status
  
  status
  string
  Const:"ok"
  subscriptionId
  string
  format: uuid
  ID of the started subscription
  
  Additional properties are allowed.
  object
  Failed subscription status
  
  status
  string
  Const:"failed"
  message
  string
  Error message describing why the subscription failed
  
  Additional properties are allowed.
  Additional properties are allowed.
  Examples
  #1 Example
  { "msgType": "subscription-status", "status": "ok", "subscriptionId": "f0823c69-7c67-4851-8d97-a525445a8b38" }
  
  #2 Example
  { "msgType": "subscription-status", "status": "failed", "message": "Unknown subscriptionId" }
- #1
  Zone events delivered by the server
  
  object
  msgType
  required
  string
  Const:"event"
  eventType
  required
  string
  Const:"zone-event"
  eventTimestamp
  required
  string
  format: date-time
  Time point at which the event was triggered
  
  eventId
  required
  string
  format: uuid
  Unique ID for this event
  
  mmsi
  required
  integer
  MMSI of the ship associated with the zone event
  
  imo
  integer
  IMO of the ship associated with the zone event, if available
  
  shipName
  string
  Name of the ship associated with the zone event, as reported via AIS
  
  array<number>
  2 items
  Location of the ship at the time the event was triggered, in [latitude, longitude] format
  
  Items:
  number
  zoneId
  required
  string
  format: uuid
  Unique ID for the zone associated with the event
  
  zoneType
  required
  string
  Type of the zone associated with the event, e.g. vts, pbp, portarea, berth, anchorage
  
  zoneEventType
  required
  string
  Signifies if the event is an arrival or a departure from the associated zone
  
  Allowed values:
  "arrival"
  "departure"
  zoneName
  required
  string
  Name of the zone associated with the event
  
  required
  array<string>
  Items:
  string
  must match: ^[A-Z]{5}$
  Additional properties are allowed.
  Examples
  #1 Example
  { "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" ] }

Messages

#1
Message IDSubscriptionRequest
Subscription request sent by the client, specifying the events to subscribe to

object
>= 2 properties
msgType
required
string
Const:"subscribe"
array<oneOf>
Specify events to subscribe to

Items:
oneOf
object
Zone event subscription request

eventType
required
string
Type of events to subscribe to

Const:"zone-event"
array<string>
Items:
string
must match: ^[A-Z]{5}$
UN/LOCODE of a port

array<string>
Items:
string
must match: ^[A-Z]{2}$
Two letter country code, i.e. two first letters of a UN/LOCODE

Additional properties are allowed.
resume
string
format: uuid
Additional properties are allowed.
tuple<object, ...optional<any>>
1 item:
object
description
Subscription status provided by the server as a response to a subscription request
object oneOf
msgType
string
Const:"subscription-status"
object
Successful subscription status

status
string
Const:"ok"
subscriptionId
string
format: uuid
ID of the started subscription

Additional properties are allowed.
object
Failed subscription status

status
string
Const:"failed"
message
string
Error message describing why the subscription failed

Additional properties are allowed.
Additional properties are allowed.
tuple<object, object, ...optional<any>>
1 item:
object
object
msgType
subscription-status
status
ok
subscriptionId
f0823c69-7c67-4851-8d97-a525445a8b38
2 item:
object
object
msgType
subscription-status
status
failed
message
Unknown subscriptionId
#2
Message IDSubscriptionStatus
Subscription status provided by the server as a response to a subscription request

object oneOf
msgType
string
Const:"subscription-status"
object
Successful subscription status

status
string
Const:"ok"
subscriptionId
string
format: uuid
ID of the started subscription

Additional properties are allowed.
object
Failed subscription status

status
string
Const:"failed"
message
string
Error message describing why the subscription failed

Additional properties are allowed.
Additional properties are allowed.
#3
Message IDZoneEvent
Zone events delivered by the server
object
msgType
required
string
Const:"event"
eventType
required
string
Const:"zone-event"
eventTimestamp
required
string
format: date-time
Time point at which the event was triggered

eventId
required
string
format: uuid
Unique ID for this event

mmsi
required
integer
MMSI of the ship associated with the zone event

imo
integer
IMO of the ship associated with the zone event, if available

shipName
string
Name of the ship associated with the zone event, as reported via AIS

array<number>
2 items
Location of the ship at the time the event was triggered, in [latitude, longitude] format

Items:
number
zoneId
required
string
format: uuid
Unique ID for the zone associated with the event

zoneType
required
string
Type of the zone associated with the event, e.g. vts, pbp, portarea, berth, anchorage

zoneEventType
required
string
Signifies if the event is an arrival or a departure from the associated zone

Allowed values:
"arrival"
"departure"
zoneName
required
string
Name of the zone associated with the event

required
array<string>
Items:
string
must match: ^[A-Z]{5}$
Additional properties are allowed.

Schemas

object
Zone event subscription request

eventType
required
string
Type of events to subscribe to

Const:"zone-event"
array<string>
Items:
string
must match: ^[A-Z]{5}$
UN/LOCODE of a port

array<string>
Items:
string
must match: ^[A-Z]{2}$
Two letter country code, i.e. two first letters of a UN/LOCODE

Additional properties are allowed.
object
Successful subscription status

status
string
Const:"ok"
subscriptionId
string
format: uuid
ID of the started subscription

Additional properties are allowed.
object
Failed subscription status

status
string
Const:"failed"
message
string
Error message describing why the subscription failed

Additional properties are allowed.

Awake.AI Voyage Events API 1.0.0

Servers

Operations

RECEIVE /

Examples

#1 Example

#2 Example

#3 Example

SEND /

Examples

#1 Example

#2 Example

Examples

#1 Example

Messages

Schemas