Marine API Documentation - Version 1

Resources - Vessel (Vessels)

A vessel represents a physical marine ship, platform or buoy. The data is sourced from multiple feeds and presents the latest version that it can find.

Resource model

Name Property Name Data Type Optional Description
Callsign callsign String No Unique identifier and official callsign
Name name String No Name of vessel or ship
Vessel vessel Array - of - string No BODC identifier for vessel - string pair of list and code from NDG Vocabulary
Position latest_position DataTimePosition No Latest position information as a Position object

Note: This model is liable to change in future API versions.

Example (JSON)

{
    callsign: "ZDLP",
    name: "RRS James Clark Ross",
    vessel: {
        vessel_list: "C17",
        vessel_code: "74JC"
    },
    latest_position: {
        latitude: -67.46707,
        longitude: -75.81744,
        datetime: "2015-02-19T09:56:22+00:00",
        timestamp: 1424339782
    }
}

Resource methods

[GET]/vessels/position

Returns all available vessels current positions.

Parameters

None.

Options

None.

Example request

URL: http://api.bas.ac.uk/marine/v1/vessels/position/

Note: Interactive examples for this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example response (200 OK)
Headers
Key Value
Content-Type application/json
Body (JSON)

Note: For brevity, only the first and last records are shown.

{
  "data": [
    {
      "callsign": "ZDLP",
      "name": "RRS James Clark Ross",
      "vessel": {
        "vessel_list": "C17",
        "vessel_code": "74JC"
      },
      "latest_position": {
        "latitude": -67.46707,
        "longitude": -75.81744,
        "datetime": "2015-02-19T09:56:22+00:00",
        "timestamp": 1424339782
      }
    },
    {
      "callsign": "ZDLS1",
      "name": "RRS Ernest Shackleton",
      "vessel": {
        "vessel_list": "C17",
        "vessel_code": "74EE"
      },
      "latest_position": {
        "latitude": -51.9,
        "longitude": -58.4,
        "datetime": "2015-02-18T18:00:00+00:00",
        "timestamp": 1424282400
      }
    },
    {
      "callsign": "MLRM6",
      "name": "RRS James Cook",
      "vessel": {
        "vessel_list": "C17",
        "vessel_code": "740H"
      },
      "latest_position": {
        "latitude": 7.4,
        "longitude": -84,
        "datetime": "2015-01-15T12:00:00+00:00",
        "timestamp": 1421323200
      }
    },
    {
      "callsign": "2FGX5",
      "name": "RRS Discovery",
      "vessel": {
        "vessel_list": "C17",
        "vessel_code": "74EQ"
      },
      "latest_position": {
        "latitude": 38.2,
        "longitude": -17.3,
        "datetime": "2015-02-18T12:00:00+00:00",
        "timestamp": 1424260800
      }
    }
  ],
  "meta": {
    "count": 4
  }
}
Statcounter

[GET]/vessel/position/{callsign}

Returns a specified vessel’s current position by its callsign.

Parameters
Name Field Name Data Type Required Valid Value(s) Description
Callsign {callsign} String Yes A callsign identifier Used to specify which vessel to return
Options

None.

Example request

URL: https://api.bas.ac.uk/marine/v1/vessels/position/ZDLP

Note: Interactive examples for this method may be covered in the examples document.

Headers
Key Value
Content-Type application/json
Accept application/json
Body (Raw)

N/A

Example response (200 Success)
Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body (JSON)
{
  "data": {
    "callsign": "ZDLP",
    "name": "RRS James Clark Ross",
    "vessel": {
      "vessel_list": "C17",
      "vessel_code": "74JC"
    },
    "latest_position": {
      "latitude": -67.4839,
      "longitude": -75.86003,
      "datetime": "2015-02-19T10:15:16+00:00",
      "timestamp": 1424340916
    }
  }
}
Example response (404 Not Found)

Using URL: https://api.bas.ac.uk/marine/v1/vessels/position/NONE.

Headers (Redundant headers removed)
Key Value
Content-Type application/json
Body
{
  "errors": {
    "details": "Callsign not found"
  }
}

Note: The format of this error will change in future API versions (to standardise against the json:api spec.

This information may be out of date whilst this website is being redeveloped. Until then, if you have any problems using an API documented here, please contact the relevant project maintainer.