Using Voyage data typically involves querying these endpoints in the Voyage API:
The following gives an introduction to using the API. To read more on voyage tracking in Vessel Insight, please look at Voyage Data concept article.
Voyage history
A typical usage scenario for voyage data combined with sensor data is to find how much fuel has a main engine consumed during past voyage. For this we use the Voyage History.
To get the last voyage for the vessel:
curl --location 'https://api.kognif.ai/voyage/api/voyage/history/imoXXX?noOfRecords=1
\--header 'Ocp-Apim-Subscription-Key: [YOUR-OCP-APIM-SUBSCRIPTION-KEY]'
\--header 'Authorization: ••••••'
The response contains the date and time for the start and the end of the voyage and this can in turn be used to aggregate sensor data for the same period.
This is an example of the response:
[
{
"id":"7e04ffec-b653-4a71-810f-de9d4ef2ea42",
"type":"voyagehistory",
"createdAt":"2024-10-31T08:00:26.4539803Z",
"customerId":"c68e7883-dac9-461e-bd02-2c1929ae82fc",
"vesselImo":"xxx",
"imo":"xxx",
"origin":{
"countryCode":"PA",
"portCode":"BLB",
"placeName":"Balboa",
"coordinates":{
"latitude":8.95,
"longitude":-79.566666
}
},
"destination":{
"countryCode":"US",
"portCode":"HOU",
"placeName":"Houston",
"coordinates":{
"latitude":29.75,
"longitude":-95.35
}
},
"rawOrigin":"PABLB",
"rawDestination":"USHOU",
"latitude":8.849522,
"longitude":-79.525795,
"draft":7.9,
"speed":0,
"distance":1567,
"heading":79,
"lastUpdated":"2024-11-05T08:00:26.3996703Z",
"messageTimestamp":"2024-11-05T07:19:29",
"eta":"2024-11-04T23:00:00",
"sourceOfMessage":0,
"cog":0.8,
"destinationMessageFromSource":"USHOU",
"voyageStartTime":"2024-11-01T01:01:00.5629876Z",
"voyageEndTime":"2024-11-04T10:00:29.6940851Z",
"averageSpeed":3.033333333333333
}
]
Attributes in response:
- Origin/Destination: Decoded origin and destinations with location
- Latitude/Longitude: Location of vessel at voyage end time
- Draft/Speed/Heading/Cog: Vessel values at voyage end time
- Distance: Voyage distance (calculated)
- lastUpdated: Time of when the voyage record was last updated
- messageTimestamp: Timestamp from latest AIS message
- eta: Estimated time of arrival at end of voyage
- sourceOfMessage: AIS source, SAT/TER (1/0)
- voyageStartTime/voyageEndTime: Voyage timings
Location history
To get information of the vessels movements and corresponding weather forecasts, the Location history is used.
curl --location 'https://api.kognif.ai/voyage/api/Location/imoXXX?fromDate=2024-11-01T01%3A01%3A01&toDate=2024-11-04T10%3A00%3A29Z'
Response:
{
"<IMO number>":[
{
"latitude":17.513334,
"longitude":119.206665,
"id":"98008762-f60d-4649-863f-cb9fd68d9268",
"customerId":"fd5b6166-fedb-4ce4-8abf-949cbe016922",
"vesselImo":"<IMO number>",
"destination":"TWTXG",
"draft":9.6,
"speed":13,
"heading":35,
"navStatus":0,
"lastUpdated":"2024-11-05T11:00:26.3996703Z",
"weatherData":{
"seaCharacteristics":{
"seaStateCode":4,
"seaStateCharacteristic":"Moderate",
"seaSwellCharacteristic":"High-Short",
"seaSwellCode":6
},
"cloudcover":100,
"humidity":77,
"pressure":1013,
"sigHeight_m":1.9,
"swellDir":330,
"swellHeight_m":4.4,
"swellPeriod_secs":0.5,
"tempC":23,
"tempF":73,
"visibility":10,
"waterTemp_C":25,
"waterTemp_F":78,
"windspeedMiles":38,
"windspeedKmph":61,
"winddirDegree":42,
"weatherCode":"122",
"precipMM":0.3,
"weatherDesc":[
{
"value":"Overcast"
}
],
"astronomy":[
{
"sunrise":"06:39 AM",
"sunset":"05:59 PM",
"moonrise":"12:02 PM",
"moonset":"12:20 AM",
"moon_phase":"First Quarter",
"moon_illumination":"50"
}
],
"isDay":false
},
"cog":null
}
]
}
Attributes in response:
- latitude/longitude: vessel position
- destination: raw destination
- draft/speed/heading: latest vessel values
- navstatus: Navigational status based on UN AIS standard:
- 0 = under way using engine; 1 = at anchor; 2 = not under command; 3 = restricted manoeuvrability; 4 = constrained by her draught; 5 = moored; 6 = aground; 7 = engaged in fishing; 8 = under way using engine;
- lastUpdated: when voyage record was updated
- weatherData: recorded weather forecast for the location at recording time