1. Home
  2. Protected: OceanIO
  3. Protected: Use cases
  4. Using Vessel Tracking Basic

Using Vessel Tracking Basic

The OceanIO offers Vessel Tracking as 2 different services:

  • Vessel Tracking Basic
  • Vessel Tracking Advanced

The following article covers use cases for Vessel Tracking Basic.

Get Current/latest position of a vessel by IMO

Its possible to get latest/current position of a vessel using IMO by requesting the following endpoint GET /tracks/vesse_imo_number/{vessel_imo_number}/positions

output:

{
  "vessel_imo_number": 9516454,
  "vessel_mmsi_number": 477845600,
  "latitude": 34.0434,
  "longitude": 143.515,
  "position_datetime": "2023-03-06T14:55:47.534000+00:00"
}

Get Current/latest position of a vessel by MMSI

Its possible to get latest/current position of a Vessel by MMSI by requesting the following endpoint GET /tracks/vessel_mmsi_number/{vessel_mmsi_number/positions

Output:

{
  "vessel_imo_number": 9516454,
  "vessel_mmsi_number": 477845600,
  "latitude": 34.0434,
  "longitude": 143.515,
  "position_datetime": "2023-03-06T14:55:47.534000+00:00"
}

Get historic positions of a Vessel

Receiving a list of historic positions is possible by firstly using the POST /tracks/historical-positions with one mandatory and 2 optional query parameters

  • IMO (required query parameter) which indicated the IMO of the Vessel to get historic positions for
  • begin_datetime (optional query parameter) which indicates the start time of requested positions. Default is 3 days
  • end_datetime (optional query parameter) which indicated the end time of requested positions. Default is now.

The response contains a track-ID which shall be used afterwards in the GET /tracks/historical-positions/{id} endpoint.

The output of the get endpoint is a list of positions for the required vessel within the given timeframe.

{
"vessel_imo_number": 9321495,
"vessel_mmsi_number": 220478000,
"positions": [
{
"longitude": 91.89111333333334,
"latitude": 5.87559,
"position_datetime": "2023-03-10 13:51:23+00:00"
},
{
"longitude": 97.65830333333334,
"latitude": 5.4213016666666665,
"position_datetime": "2023-03-11 11:24:58+00:00"
},
{
"longitude": 100.45943333333334,
"latitude": 3.218471666666667,
"position_datetime": "2023-03-11 23:30:45+00:00"
},
{
"longitude": 103.29039166666666,
"latitude": 1.2936016666666668,
"position_datetime": "2023-03-12 11:36:11+00:00"
},
{
"longitude": 104.635405,
"latitude": 1.6106433333333334,
"position_datetime": "2023-03-12 18:25:32+00:00"
}
]
}

FAQ:

Latest position:

Q: Do Vessel Tracking Basic offer the possibility to get current position on any vessel not only a Cargo Vessel?
A: Yes, any Vessel with an AIS transponder is supported in Vessel Tracking Basic

Q: What is the frequency of updates for latest/current position?
A: Current/latest position is normally updated every 15 minutes but it really depends on the vessels current position and can vary up to a couple of hours.

Historic positions:

Q: Can I request historic positions multiple times for one historical track id?
A: No, once you received data once for a historical_track_id it is not possible to receive data again. (without posting a new historical track)

Q: What is the frequency of updates for historic positions?
A: Sample rate for historic positions is 12 hours.

Q: Why is my historic position not updated to todays date? There are more than 12 hours since my last update
A: If the Vessel is currently operating the the South China Sea, updates may be delayed due to Satellite congestion

Q: Can I request position and historic positions for Container Vessels or all types?
 A: All Vessel types are supported in Vessel Track Basic

Q: Can I request historic positions for more than a year back?
A: Yes