> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-feat-trade-intel-sdk.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
This is a paid Routing Data endpoint. See [Entitlements and Paid Features](/api-docs/useful-info/entitlements) for access requirements and non-entitled responses.
This endpoint requires the destination port ID (`port_id`) and the previous port ID (`previous_port_id`) for the vessel leg you want to forecast.
## How to find the port IDs
If you are starting from a tracked container, call [`GET /v2/containers/{id}/map_geojson`](/api-docs/api-reference/containers/get-container-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`.
## OpenAPI
````yaml get /vessels/{id}/future_positions
openapi: 3.0.0
info:
title: Terminal49 API Reference
version: 0.2.0
contact:
name: Terminal49 API support
url: https://www.terminal49.com
email: support@terminal49.com
description: >-
The Terminal 49 API offers a convenient way to programmatically track your
shipments from origin to destination.
Please enter your API key into the "Variables" tab before using these
endpoints within Postman.
x-label: Beta
termsOfService: https://www.terminal49.com/terms
servers:
- url: https://api.terminal49.com/v2
description: Production
security:
- authorization: []
tags:
- name: Containers
- name: Custom Field Definitions
- name: Custom Field Options
- name: Custom Fields
- name: Shipments
- name: Locations
- name: Events
- name: Tracking Requests
- name: Webhooks
- name: Webhook Notifications
- name: Ports
- name: Metro Areas
- name: Terminals
- name: Routing (Paid)
- name: Documents
- name: Email Submissions
- name: Document Schemas
- name: Search
- name: Parties
- name: Trade Intelligence
description: >-
Trade intelligence answers questions about who imports what into the US,
from where, on which carriers, and how that changes over time. The data is
US import bill-of-lading records (US Customs vessel manifests): every
ocean container landed at a US port (plus US-bound cargo landed at
Vancouver, BC) from January 2022 to today, refreshed daily. It does not
include air freight, exports, or domestic moves.
**Access.** Trade intelligence is enabled per account. Accounts without it
receive `403 Forbidden` with `{"error": "Trade intelligence is not enabled
for this account"}`; contact sales@terminal49.com to enable it. Requests
are limited to roughly 120 per minute per account (`429` with `{"error":
"Rate limit exceeded; retry in a minute"}`).
**Format.** These endpoints accept and return plain JSON, not JSON:API.
Send `Content-Type: application/json` on `POST` requests and authenticate
exactly like every other v2 endpoint (`Authorization: Token
YOUR_API_KEY`).
**Typical flow.** Resolve a name or product first, then analyze:
`companies/search` or `commodities/search` give you the exact
`company_name` or `hs4` to pass to `companies/profile`, `importers/top`,
`trends`, or `breakdown`. Container and bill of lading numbers go straight
to `containers/lookup` and `bills_of_lading/lookup`.
**Reading the numbers.**
- **Volume is physical containers.** Each box is counted once, even when
it appears on several bills of lading. A container carrying several HS
codes counts once per code and companies can share containers, so do not
add volumes across HS codes or companies; take market totals from `trends`
or `breakdown` without a company filter.
- **Estimated value is a modelled USD estimate**, not the declared customs
value.
- **The current month is partial.** `trends` and `breakdown` include it by
default; `companies/profile` and `importers/top` use full calendar months.
Compare full months against the same months a year earlier.
- **Absent volume is not small volume.** Importers can ask US Customs to
withhold their name from manifests, and much large-retail freight is
booked under forwarders or suppliers. Treat a company's figures as a
floor, never as its size.
- **One company, many names.** Company names are normalized but split by
state, and large importers use several names (distribution, merchandising,
and DC entities). Related entities are separate companies; report them
separately. `companies/search` ranks by match quality, not by size.
- **Companies are the consignee or notify party on the bill.** Forwarders,
NVOCCs, and customs brokers appear alongside cargo owners. A high
notify-party share, or LOGISTICS, FREIGHT, SHIPPING, CUSTOMS, or BROKERAGE
in the name, usually indicates a logistics provider.
- **Carriers, countries, and ports use the manifests' spellings**, and
carriers appear under spelling variants (for example `CMA CGM` and `CMA
CGM AMERICA LLC`). Filter with substrings and merge variants before
computing shares.
- **HS4 descriptions are truncated.** Check `common_goods` from
`commodities/search` before relying on a code.
paths:
/vessels/{id}/future_positions:
parameters:
- schema:
type: string
name: id
in: path
required: true
get:
tags:
- Routing (Paid)
- Vessels
summary: Get vessel future positions
description: >-
Returns the estimated route between two ports for a given vessel.
The timestamp of the positions has fixed spacing of one
minute. This is a paid feature. Please contact
sales@terminal49.com.
operationId: get-vessels-id-future-positions
parameters:
- schema:
type: string
format: uuid
in: query
name: port_id
description: The destination port id
required: true
- schema:
type: string
format: uuid
in: query
name: previous_port_id
description: The previous port id
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/vessel_with_positions'
links:
type: object
properties:
self:
type: string
format: uri
'403':
description: Forbidden - Routing data feature is not enabled for this account
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
example: '403'
title:
type: string
example: Forbidden
detail:
type: string
example: Routing data feature is not enabled for this account
components:
schemas:
vessel_with_positions:
title: Vessel with positions model
type: object
properties:
id:
type: string
format: uuid
type:
type: string
enum:
- vessel
attributes:
type: object
properties:
name:
type: string
description: The name of the ship or vessel
imo:
type: string
description: International Maritime Organization (IMO) number
nullable: true
mmsi:
type: string
description: Maritime Mobile Service Identity (MMSI)
nullable: true
latitude:
type: number
description: The current latitude position of the vessel
nullable: true
longitude:
type: number
description: The current longitude position of the vessel
nullable: true
nautical_speed_knots:
type: number
description: The current speed of the ship in knots (nautical miles per hour)
nullable: true
navigational_heading_degrees:
type: number
description: >-
The current heading of the ship in degrees, where 0 is North, 90
is East, 180 is South, and 270 is West
nullable: true
position_timestamp:
type: string
format: date-time
description: >-
The timestamp of when the ship's position was last recorded, in
ISO 8601 date and time format
nullable: true
positions:
type: array
description: Array of estimated future positions
items:
type: object
properties:
latitude:
type: number
longitude:
type: number
heading:
type: number
nullable: true
timestamp:
type: string
format: date-time
estimated:
type: boolean
required:
- latitude
- longitude
- timestamp
- estimated
required:
- id
- type
- attributes
securitySchemes:
authorization:
name: Authorization
type: apiKey
in: header
description: >-
Use a Terminal49 API key in the `Authorization` header with the `Token`
prefix.
`Authorization: Token YOUR_API_KEY`
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.