Vessel movement history

Screening a vessel produces two views of where it has been. GET /porthistory lists the ports it called at over the lookback period. GET /non-reporting lists the stretches where it stopped reporting a position at all.

The two take different ids. Port calls hang off the SHIP_MOVE_HIST screen result; reporting gaps hang off the transaction.

Port calls

Find the id

In the screen_results array returned by GET /transaction, find the object whose check is SHIP_MOVE_HIST.

{
  "check": "SHIP_MOVE_HIST",
  "creation_date": "2022-04-19T08:38:36Z",
  "id": 9374376,
  "resource_uri": "/api/v1/screenresult/9374376",
  "result_code": null,
  "status": "OK"
}

Retrieve the port history

Pass that id as screen_result_id.

Each object is one port call, with entered and departed timestamps and the severity the call carries. A departed of null means the vessel had not left when the screening ran.

{
  "meta": {
    "limit": 20,
    "next": "/api/v1/porthistory?screen_result_id=14837193&api_key=&username=&order_by=-entered&limit=20&offset=21",
    "offset": 1,
    "previous": null,
    "total_count": 1162
  },
  "objects": [
    {
      "category": "",
      "country_name": "Bangladesh",
      "departed": null,
      "entered": "2023-11-07T20:54:52+00:00",
      "id": 122455254,
      "port_name": "Chittagong",
      "resource_uri": "/api/v1/porthistory/122455254",
      "screenresult": "/api/v1/screenresult/9783006",
      "severity": "OK"
    },
    {
      "category": "",
      "country_name": "Singapore",
      "departed": "2023-10-22T23:17:26+00:00",
      "entered": "2023-10-22T20:59:32+00:00",
      "id": 122455256,
      "port_name": "Singapore Offshore Terminals",
      "resource_uri": "/api/v1/porthistory/122455256",
      "screenresult": "/api/v1/screenresult/9783006",
      "severity": "OK"
    },
    {
      "category": "",
      "country_name": "Singapore",
      "departed": "2023-10-22T20:59:32+00:00",
      "entered": "2023-10-22T17:41:35+00:00",
      "id": 122455212,
      "port_name": "Tanjung Langsat",
      "resource_uri": "/api/v1/porthistory/122455212",
      "screenresult": "/api/v1/screenresult/9783001",
      "severity": "OK"
    },
    {
      "category": "",
      "country_name": "Singapore",
      "departed": "2023-10-22T20:59:32+00:00",
      "entered": "2023-10-22T06:40:40+00:00",
      "id": 122455341,
      "port_name": "Singapore Offshore Terminals",
      "resource_uri": "/api/v1/porthistory/122455341",
      "screenresult": "/api/v1/screenresult/9783011",
      "severity": "OK"
    },
    {
      "category": "",
      "country_name": "Indonesia",
      "departed": "2023-10-18T17:19:08+00:00",
      "entered": "2023-10-16T21:18:52+00:00",
      "id": 122455259,
      "port_name": "Gresik",
      "resource_uri": "/api/v1/porthistory/122455259",
      "screenresult": "/api/v1/screenresult/9783006",
      "severity": "OK"
    },
    {
      "category": "",
      "country_name": "Indonesia",
      "departed": "2023-10-16T17:42:02+00:00",
      "entered": "2023-10-15T20:19:20+00:00",
      "id": 122455215,
      "port_name": "Surabaya",
      "resource_uri": "/api/v1/porthistory/122455215",
      "screenresult": "/api/v1/screenresult/9783001",
      "severity": "OK"
    }
  ]
}

A well-travelled vessel produces thousands of calls. This one has 1,162, so page with limit and offset or follow meta.next. Two further parameters are worth knowing: order_by takes entered or -entered and defaults to newest first, and severity__in filters on the severity of the call, with 20 for OK, 40 for WARNING and 60 for CRITICAL.

Periods of non-reporting

A reporting gap is a stretch during the screening lookback period where the vessel sent no position. The gap threshold that counts as one is set by your account configuration.

Non-reporting is an addon

Contact your Pole Star representative to have it enabled on your account.

This endpoint takes the transaction id, not a screen result id, in the transaction parameter.

Each object describes one gap: when and where it started, when and where it ended, how long it ran in duration_seconds, the draught at each end, and the zones the vessel was in. draught_change says whether the vessel's draught changed across the gap, which is the signal that something was loaded or discharged out of sight.

{
  "meta": {
    "limit": 10,
    "next": "/api/v1/non-reporting?transaction=2854829&api_key=&username=&limit=10&offset=10",
    "offset": 0,
    "previous": null,
    "total_count": 34
  },
  "objects": [
    {
      "draught_change": false,
      "duration_seconds": 98245,
      "end_course": 109,
      "end_datetime": "2023-12-06T02:33:17",
      "end_draught": 13.1,
      "end_latitude": 34.5688629150391,
      "end_longitude": 23.150032043457,
      "end_zones": [],
      "id": 18938659,
      "overall_draught_change": false,
      "overall_severity": "OK",
      "severity": "OK",
      "start_course": 104,
      "start_datetime": "2023-12-04T23:15:52",
      "start_draught": 13.1,
      "start_latitude": 36.2875061035156,
      "start_longitude": 16.4916229248047,
      "start_zones": [],
      "sts_risk_overall_severity": "OK",
      "sts_risk_severity": null,
      "transaction": "/api/v1/transaction/2854829",
      "transaction_id": 2854829
    },
    {
      "draught_change": false,
      "duration_seconds": 222436,
      "end_course": 110,
      "end_datetime": "2023-12-04T05:31:07",
      "end_draught": 13.1,
      "end_latitude": 37.3464851379394,
      "end_longitude": 12.007209777832,
      "end_zones": [],
      "id": 18938658,
      "overall_draught_change": false,
      "overall_severity": "OK",
      "severity": "OK",
      "start_course": 74,
      "start_datetime": "2023-12-01T15:43:51",
      "start_draught": 13.1,
      "start_latitude": 36.3815155029297,
      "start_longitude": -2.10136675834656,
      "start_zones": [],
      "sts_risk_overall_severity": "OK",
      "sts_risk_severity": null,
      "transaction": "/api/v1/transaction/2854829",
      "transaction_id": 2854829
    },
    {
      "draught_change": false,
      "duration_seconds": 157650,
      "end_course": 99,
      "end_datetime": "2023-11-14T14:42:15",
      "end_draught": 13.1,
      "end_latitude": 23.4529724121094,
      "end_longitude": -81.7180709838867,
      "end_zones": [],
      "id": 18938657,
      "overall_draught_change": false,
      "overall_severity": "OK",
      "severity": "OK",
      "start_course": 150,
      "start_datetime": "2023-11-12T18:54:45",
      "start_draught": 13.1,
      "start_latitude": 28.0621585845947,
      "start_longitude": -88.9700622558594,
      "start_zones": [],
      "sts_risk_overall_severity": "OK",
      "sts_risk_severity": null,
      "transaction": "/api/v1/transaction/2854829",
      "transaction_id": 2854829
    }
  ]
}

severity grades the individual gap and overall_severity grades the vessel's gap record as a whole, so a single quiet stretch on an otherwise clean vessel reads differently from one on a vessel that goes dark often. sts_risk_severity grades the ship-to-ship risk the gap carries, and is null where none was assessed.

Screening Vessels

Registering a vessel, and reading the SHIP_MOVE_HIST id this page needs.

Additional Checks

Positional discrepancy, STS pairing and the rest of the detailed checks.

Vessel Tracking

Live positions and notifications once screening is done.

Port calls#

Find the id#

Retrieve the port history#

Periods of non-reporting#

Related#

Port calls

Find the id

Retrieve the port history

Periods of non-reporting

Related