Get vessel future positions

Retrieve a vessel’s estimated future route between two ports from the Terminal49 API, returning a sequence of positions spaced one minute apart.

GET /vessels/{id}/future_positions

Get vessel future positions

cURL

curl --request GET \
  --url https://api.terminal49.com/v2/vessels/{id}/future_positions \
  --header 'Authorization: <api-key>'

200

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "attributes": {
      "name": "<string>",
      "imo": "<string>",
      "mmsi": "<string>",
      "latitude": 123,
      "longitude": 123,
      "nautical_speed_knots": 123,
      "navigational_heading_degrees": 123,
      "position_timestamp": "2023-11-07T05:31:56Z",
      "positions": [
        {
          "latitude": 123,
          "longitude": 123,
          "timestamp": "2023-11-07T05:31:56Z",
          "estimated": true,
          "heading": 123
        }
      ]
    }
  },
  "links": {
    "self": "<string>"
  }
}

This is a paid Routing Data endpoint. See Entitlements and Paid Features for access requirements and non-entitled responses.

Required query parameters

This endpoint requires both port IDs for the vessel leg you want to forecast:

Parameter	Required	Description
port_id	Yes	Destination port UUID for the forecasted leg
previous_port_id	Yes	Previous port UUID for the same vessel leg

How to find the port IDs

If you are starting from a tracked container, call GET /v2/containers/{id}/map_geojson and inspect the port features. Each port feature includes:

• properties.location_id - the port UUID to pass as port_id or previous_port_id
• properties.ports_sequence - the route order
• properties.label - route label such as POL, POD, or transshipment labels

Use the destination port’s location_id as port_id, and the preceding port’s location_id as previous_port_id.

Authorizations

Authorization · string · header · required

Use a Terminal49 API key in the Authorization header with the Token prefix.

Authorization: Token YOUR_API_KEY

Path Parameters

id · string · required

Query Parameters

port_id · string<uuid> · required

The destination port id

previous_port_id · string<uuid> · required

The previous port id

Response

200

application/json

OK

data · Vessel with positions model · object

Show child attributes

links · object

Show child attributes