2. Home
  4. Protected: OceanIO
  6. Protected: Use cases
  8. 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,
  "sog": 2.9,
  "nav_status": 1
  "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,
  "sog": 2.9,
  "nav_status": 1 
  "position_datetime": "2023-03-06T14:55:47.534000+00:00" 
}

Nagivational status description:

An AIS navigational status is a signal reported by the vessel, which describes the status of the vessel in real-time.

You can understand the vessel’s activity by reading the navigational status code. The code can have different values ranging from 0 to 15.

  • Nav_status = 0
    • Underway using engine
      • The vessel is underway using the engine when :
        – It is not aground
        – It is not at anchor
        – It was not attached to a dock, the shore or any other stationary object
  • nav_status = 1
    • at anchor
  • nav_status = 2
    • not under command
  • nav_status = 3
    • restricted maneuverability
  • nav_status = 4
    • constrained by her draught
  • nav_status = 5
    • moored
  • nav_status = 6
    • aground 
  • nav_status = 7
    • engaged in fishing
  • nav_status = 8
    • underway sailing
  • nav_status = 9
    • reserved for future amendment of navigational status for ships carrying dangerous goods (DG), harmful substances(HS), or IMO hazard or pollutant category C, high-speed craft (HSC).
  • nav_status = 10
    • reserved for future amendment of navigational status for ships carrying dangerous goods (DG), harmful substances (HS) or marine pollutants (MP), or IMO hazard or pollutant category A, wing in the ground (WIG).
  • nav_status = 11
    • power-driven vessel towing astern.
  • nav_status = 12
    • power-driven vessel pushing ahead or towing alongside.
  • nav_status = 13
    • reserved for future use.
  • nav_status = 14
    • AIS-SART Active (Search and Rescue Transmitter), AIS-MOB (Man Overboard), AIS-EPIRB (Emergency Position Indicating Radio Beacon)
  • nav_status = 15
    • undefined = default (also used by AIS-SART, MOB-AIS, and EPIRB-AIS under test).

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