Overview

Welcome to the Clearwater Tracking API.

You can use our API to access various API endpoints, which can provide you access to information on vessels and alerts.

API Endpoint

The URL for the Clearwater API Endpoint is dependent upon the client portal you want to access.

https://{host}/api/v1

The {host} value will usually be www.clearwatertrackingsystem.com but details will be provided by the Clearwater Ops team if you should use something different.

Authentication

To authenticate against the API, use this code:

$ curl https://{host}/api/v1/{endpoint}?api_key={yourapikey}

Make sure to replace {host} with the hostname provided, and {yourapikey} with your API key.

We use API keys to allow access to the API. Permissions will be set based on your requirements, so some endpoints may not be available to all users.

Required Query Parameters

Parameter	Description
api_key	API key

The api_key parameter must be included in the query string of all requests to the server.

Alerts

Get all alerts

$ curl https://{host}/api/v1/alert?api_key={yourapikey}

The above command returns JSON structured like this:

[
  {
    "id": 1,
    "title": "Attempted robbery on an anchored bulk carrier in Diamond Harbour Anchorage, Kolkata India",
    ...
  },
  {
    "id": 2,
    "title": "Attempted robbery on a bulk carrier, Bangladesh",
    ...
  }
]

This endpoint retrieves all alerts.

HTTP Request

GET https://{host}/api/v1/alert

Optional Query Parameters

Parameter	Default	Description
format	json	string (`json` or `csv`) Desired format.
download	false	boolean (`true` or `false`) Force the file to download, used in conjunction with the CSV format.

Get a specific alert

$ curl https://{host}/api/v1/alert/2?api_key={yourapikey}

The above command returns JSON structured like this:

{
  "id": 1,
  "title": "Attempted robbery on an anchored bulk carrier in Diamond Harbour Anchorage, Kolkata India",
  ...
}

This endpoint retrieves a specific alert.

HTTP Request

GET https://{host}/api/v1/alert/{id}

Required URL Parameters

Parameter	Description
id	The ID of the alert to retrieve

Vessels

Get all vessels

$ curl https://{host}/api/v1/vessel?api_key={yourapikey}

The above command returns JSON structured like this:

[
    {
        "id": 1,
        "name": "BEN MY CHREE",
        "imo": 9170705,
        "location": {
            "id": 12345,
            "timestamp": "2018-01-02T03:04:05Z",
            "lat": 54.0180566667,
            "lon": -3.940665,
            "course": 111,
            "speed": 18.4
        }
    },
    {
        "id": 2,
        "name": "MANANNAN",
        "imo": 9176072,
        "location": {
            "id": 12346,
            "timestamp": "2018-01-02T03:04:05Z",
            "lat": 53.3888733333,
            "lon": -3.009675,
            "course": 115,
            "speed": 0
        }
    }
]

This endpoint retrieves all vessels.

HTTP Request

GET https://{host}/api/v1/vessel

Optional Query Parameters

Parameter	Default	Description
format	json	string (`json` or `csv`) Desired format.
download	false	boolean (`true` or `false`) Force the file to download, used in conjunction with the CSV format.
include_ais	false	boolean (`true` or `false`) Include the latest AIS details for each vessel.

Get a specific vessel

$ curl https://{host}/api/v1/vessel/2?api_key={yourapikey}

The above command returns JSON structured like this:

{
    "id": 2,
    "name": "MANANNAN",
    "imo": 9176072,
    "location": {
        "id": 12346,
        "timestamp": "2018-01-02T03:04:05Z",
        "lat": 53.3888733333,
        "lon": -3.009675,
        "course": 115,
        "speed": 0
    }
}

This endpoint retrieves a specific vessel.

HTTP Request

GET https://{host}/api/v1/vessel/{id}

Required URL Parameters

Parameter	Description
id	The ID of the vessel to retrieve

Optional Query Parameters

Parameter	Default	Description
include_ais	false	boolean (`true` or `false`) Include the latest AIS details for the vessel.

Get the location history for a vessel

$ curl https://{host}/api/v1/vessel/2/history?api_key={yourapikey}

The above command returns JSON structured like this:

[
    {
        "id": 12346,
        "timestamp": "2018-01-02T03:04:05Z",
        "lat": 53.3888733333,
        "lon": -3.009675,
        "course": 115,
        "speed": 0
    },
    {
        "id": 12344,
        "timestamp": "2018-01-02T02:04:05Z",
        "lat": 53.3888733333,
        "lon": -3.009675,
        "course": 115,
        "speed": 0
    },
    ...
]

This endpoint retrieves the location history for a specific vessel.

HTTP Request

GET https://{host}/api/v1/vessel/{id}/history

Required URL Parameters

Parameter	Description
id	The ID of the vessel

Optional Query Parameters

Parameter	Default	Description
format	json	string (`json` or `csv`) Desired format.
download	false	boolean (`true` or `false`) Force the file to download, used in conjunction with the CSV format.
limit	50	integer Number of records to return.
offset	0	integer Offset from the previous request.

Set the location of a vessel

$ curl -X POST https://{host}/api/v1/vessel/2/location?api_key={yourapikey} \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2018-02-03 04:05:06 UTC",
    "lat": 53.3888,
    "lon": -3.0096,
    "speed": 10.0,
    "course": 92
  }'

On success, the above command returns JSON structured like this:

{
  "status": 201,
  "message": "Location saved",
  "additional_information": []
}

If there is a problem, you'll get a response like this:

{
  "status": 400,
  "message": "Unable to validate location",
  "additional_information": [
    "Unable to parse timestamp."
  ]
}

This endpoint updates the latest location for a specific vessel. Its use is restricted to selected clients who may use a third party tracking provider.

HTTP Request

POST https://{host}/api/v1/vessel/{id}/location

Required URL Parameters

Parameter	Description
id	The ID of the vessel to retrieve

POST Body Content

The new location must be encoded as a JSON object and posted to the API endpoint in the body of the request. The request should set a Content-Type: application/json header.

Field	Description
timestamp	string (required) Date and time (UTC) e.g. 2018-02-03T04:05:06Z or 2018-02-03 04:05:06 UTC
lat	float (required) Latitude in decimal degrees
lon	float (required) Longitude in decimal degrees
speed	float Speed in knots
course	integer Course in degrees
sourceId	integer Identifier in source system. Must be unique if included.

Errors

The Clearwater API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong or you don't have permission to perform the requested action.
404	Not Found -- The specified item could not be found.
405	Method Not Allowed -- You tried to use an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.