Track a vessel with the PurpleTRAC API

Tracking a screened vessel gives you position reports and event notifications for as long as the track runs, plus a Trade Report covering the voyage once it stops.

Screening comes first. A vessel needs a transaction id before it can be tracked, and Screening Vessels shows how to get one.

Enable tracking

PUT /transaction/{id}/track starts the track. The {id} path parameter is the transaction id from screening.

Start and end options

The request body configures where the track begins and ends. Every field is optional, so an empty object {} tracks the vessel indefinitely.

{
    "client_reference": null,
    "departure_port": null,
    "departure_date": null,
    "interim_ports": [],
    "destination_port": null,
    "arrival_date": null
}

You can amend all of these once the track is running, to correct a port or extend the duration. Updating Voyage Details has that call.

The response

You get back the transaction with its tracking configuration and its current status.

{
  "added_via": "MANUAL",
  "ais_gap_status": "F",
  "ais_received": null,
  "ais_reporting": true,
  "auto_deregister": false,
  "auto_deregistered": false,
  "auto_register": true,
  "blv": null,
  "carbon_rating_screen": false,
  "client_reference": null,
  "closed_date": null,
  "container_screen_id": null,
  "creation_date": "2023-12-06T16:03:55.335567",
  "has_gaps": true,
  "id": 2854829,
  "inmarsatc_expected": null,
  "inmarsatc_interval": 2,
  "inmarsatc_received": null,
  "inmarsatc_reporting": true,
  "only_tracking_by_ais": false,
  "overall_severity": "WARNING",
  "registered_date": null,
  "registered_name": "9744051",
  "report_generation_complete": true,
  "resource_uri": "/api/v1/transaction/2854829",
  "screened_date": "2023-12-06T16:04:02.896743",
  "screening_status": "WARNING",
  "ship": "/api/v1/shipdetails/376523",
  "status": "R",
  "tracking_date": null,
  "tracking_expiry": null,
  "transceiver_domain": "",
  "transceiver_domain_id": "",
  "user": "/api/v1/user/6913",
  "voyage": null
}

Tracking status

A tracking request moves the transaction to Ready to Track, "status": "R". Our internal tracking service then approves it and the status becomes Approved, "status": "A". Positions and notifications are generated from that point, so a vessel sitting at R produces neither.

Check the status with GET /transaction and read the status field in the main body of the response.

Ready to Track: "status": "R"

Approved: "status": "A"

Read the right status field

The last_position and ship objects in the same response carry their own status fields. Neither reports the tracking status.

Read positions

GET /position returns the positional data generated since tracking began. Pass the transaction id in the id query parameter.

Positions take time to appear

A vessel often has no positions when tracking is first enabled. Wait for the first one to be generated before treating an empty response as a fault.

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 4
    },
    "objects": [
        {
            "creation_date": "2023-12-07 11:59:16.054895+00:00",
            "destination": "EG PSD",
            "destination_eta": "2023-12-07 17:00:00+00:00",
            "heading": 114.0,
            "info": [],
            "latitude": 32.137417,
            "longitude": 30.847609,
            "outlier": false,
            "position_type": "AIS",
            "resource_uri": "",
            "speed": 12.8,
            "status": null,
            "status_timestamp": "2023-12-07 11:57:21+00:00",
            "timestamp": "2023-12-07 11:57:21+00:00",
            "transaction": "/api/v1/transaction/2854829"
        },
        {
            "creation_date": "2023-12-07 11:59:14.441966+00:00",
            "destination": "EG PSD",
            "destination_eta": "2023-12-07 17:00:00+00:00",
            "heading": 115.0,
            "info": [],
            "latitude": 32.163326,
            "longitude": 30.783585,
            "outlier": false,
            "position_type": "AIS",
            "resource_uri": "",
            "speed": 12.8,
            "status": null,
            "status_timestamp": "2023-12-07 11:57:21+00:00",
            "timestamp": "2023-12-07 11:40:32+00:00",
            "transaction": "/api/v1/transaction/2854829"
        },
        {
            "creation_date": "2023-12-07 10:38:05.183160+00:00",
            "destination": "EG PSD",
            "destination_eta": "2023-12-07 17:00:00+00:00",
            "heading": 112.0,
            "info": [],
            "latitude": 32.26791,
            "longitude": 30.494967,
            "outlier": false,
            "position_type": "AIS",
            "resource_uri": "",
            "speed": 12.4,
            "status": null,
            "status_timestamp": "2023-12-07 10:23:53+00:00",
            "timestamp": "2023-12-07 10:23:53+00:00",
            "transaction": "/api/v1/transaction/2854829"
        },
        {
            "creation_date": "2023-12-06 16:04:00.311525+00:00",
            "destination": "EG PSD",
            "destination_eta": "2023-12-07 17:00:00+00:00",
            "heading": 106.0,
            "info": [],
            "latitude": 33.791149,
            "longitude": 25.810593,
            "outlier": false,
            "position_type": "AIS",
            "resource_uri": "",
            "speed": 12.0,
            "status": null,
            "status_timestamp": "2023-12-06 13:52:58+00:00",
            "timestamp": "2023-12-06 13:52:58+00:00",
            "transaction": "/api/v1/transaction/2854829"
        }
    ]
}

Positions come back in the standard meta and objects envelope, newest first, so page through meta.next on a long track.

Read notifications

GET /notification returns the events raised against the track. Which query parameter you use depends on what was screened: transaction for a vessel screening, blv for a Bill of Lading verification.

Vessel screening

Bill of lading

Your account's notification settings decide which events are raised and what severity each one carries. Your account admin edits those settings in the PurpleTRAC UI. Tracking Notifications lists every event a track can produce.

Notifications take time to appear

As with positions, a newly enabled track has nothing to return until the first event is generated.

The response below is trimmed to three of the ten objects on the first page.

{
  "meta": {
    "limit": 10,
    "next": "/api/v1/notification?transaction=2854829&order_by=-event_date&username=&api_key=&limit=10&offset=10",
    "offset": 0,
    "previous": null,
    "total_count": 24
  },
  "objects": [
    {
      "acknowledged": false,
      "blv": null,
      "cleared": false,
      "comment": "",
      "creation_date": "2023-12-09T04:37:25.299207+00:00",
      "document_id": null,
      "event": "POSITION_PORT_EXIT",
      "event_date": "2023-12-09T04:17:29+00:00",
      "id": 52605259,
      "last_updated_date": "2023-12-09T04:37:25.299229+00:00",
      "parent_notification_id": null,
      "related_obj_id": "EGRSH",
      "related_text": "Ras Shukheir, Egypt",
      "resource_uri": "/api/v1/notification/52605259",
      "severity": "OK",
      "transaction": "/api/v1/transaction/2854829",
      "updated_since_creation": false,
      "user": "/api/v1/user/6913"
    },
    {
      "acknowledged": false,
      "blv": null,
      "cleared": false,
      "comment": "",
      "creation_date": "2023-12-09T03:16:11.036461+00:00",
      "document_id": null,
      "event": "POSITION_PORT_ENTRY",
      "event_date": "2023-12-09T03:04:18+00:00",
      "id": 52603048,
      "last_updated_date": "2023-12-09T03:16:11.036500+00:00",
      "parent_notification_id": null,
      "related_obj_id": "EGRSH",
      "related_text": "Ras Shukheir, Egypt",
      "resource_uri": "/api/v1/notification/52603048",
      "severity": "OK",
      "transaction": "/api/v1/transaction/2854829",
      "updated_since_creation": false,
      "user": "/api/v1/user/6913"
    },
    {
      "acknowledged": false,
      "blv": null,
      "cleared": false,
      "comment": "",
      "creation_date": "2023-12-08T22:27:17.766674+00:00",
      "document_id": null,
      "event": "POSITION_PORT_EXIT",
      "event_date": "2023-12-08T22:15:18+00:00",
      "id": 52594799,
      "last_updated_date": "2023-12-08T22:27:17.766701+00:00",
      "parent_notification_id": null,
      "related_obj_id": "EGZAF000",
      "related_text": "Za'farana Terminal, Egypt",
      "resource_uri": "/api/v1/notification/52594799",
      "severity": "OK",
      "transaction": "/api/v1/transaction/2854829",
      "updated_since_creation": false,
      "user": "/api/v1/user/6913"
    }
  ]
}

The event field carries the event name you match on. related_obj_id and related_text name whatever the event is about, a port in these examples. severity reflects the band configured on your account.

Stop tracking

The Trade Report is only generated once tracking has stopped. If you configured an end point when you enabled the track, that happens on its own and the report follows automatically.

To stop a track yourself, send PUT /transaction/{id} with "status": "C", the same call used to archive a screening.

Stopping a track archives the vessel

The transaction is archived at the same time, so it leaves your active list.

The response is the transaction with "status": "C".

{
  "added_via": "MANUAL",
  "ais_gap_status": "F",
  "ais_received": null,
  "ais_reporting": true,
  "auto_deregister": true,
  "auto_deregistered": false,
  "auto_register": true,
  "blv": null,
  "carbon_rating_screen": false,
  "client_reference": "my custom reference",
  "closed_date": null,
  "container_screen_id": null,
  "creation_date": "2023-12-05T13:24:46.500470",
  "has_gaps": true,
  "id": 2849764,
  "inmarsatc_expected": null,
  "inmarsatc_interval": 2,
  "inmarsatc_received": null,
  "inmarsatc_reporting": true,
  "only_tracking_by_ais": false,
  "overall_severity": "WARNING",
  "registered_date": null,
  "registered_name": "9221126",
  "report_generation_complete": true,
  "resource_uri": "/api/v1/transaction/2849764",
  "screened_date": "2023-12-05T13:39:33.980235",
  "screening_status": "WARNING",
  "ship": "/api/v1/shipdetails/272962",
  "status": "C",
  "tracking_date": null,
  "tracking_expiry": null,
  "transceiver_domain": "",
  "transceiver_domain_id": "",
  "user": "/api/v1/user/6913",
  "voyage": null
}

Collect the trade report

The Trade Report covers the vessel's voyage and the events raised during the tracking period. Fetch it with GET /trade_report, passing the transaction id in the transaction_id query parameter.

The response is the PDF itself. A report that has not finished generating returns 500 with an empty body, so retry after a short wait.

Tracking Notifications

Every event a track can raise, with the condition that triggers it.

Managing Additional Entities

Add and remove screened counterparties while the track runs.

Updating Voyage Details

Change ports, dates and tracking expiry in flight.

Tracking a Vessel

Enable tracking#

Start and end options#

The response#

Tracking status#

Read positions#

Read notifications#

Stop tracking#

Collect the trade report#

Related#

Enable tracking

Start and end options

The response

Tracking status

Read positions

Read notifications

Stop tracking

Collect the trade report

Related