> ## 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 a vessel by ID > Retrieve a vessel from the Terminal49 API using its internal vessel ID, including name, IMO number, and optional position data for paid plan accounts. ## OpenAPI ````yaml get /vessels/{id} 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}: parameters: - schema: type: string name: id in: path required: true - schema: type: string format: date-time example: '2025-05-20T00:00:00Z' name: show_positions[from_timestamp] in: query description: ISO 8601 timestamp to filter positions from. 7 days by default. required: false - schema: type: string format: date-time example: '2025-05-24T00:00:00Z' name: show_positions[to_timestamp] in: query description: ISO 8601 timestamp to filter positions up to. Current time by default. required: false get: tags: - Vessels summary: Get a vessel using the id description: >- Returns a vessel by id. `show_positions` is a paid feature. Please contact sales@terminal49.com. operationId: get-vessels-id responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/vessel' '403': description: Forbidden - Feature not enabled content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string example: '403' source: type: object nullable: true title: type: string example: Forbidden detail: type: string example: Routing data feature is not enabled for this account components: schemas: vessel: title: vessel 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 example: Ever Given imo: type: string description: International Maritime Organization (IMO) number nullable: true example: '9811000' mmsi: type: string description: Maritime Mobile Service Identity (MMSI) nullable: true example: '353136000' latitude: type: number description: The current latitude position of the vessel nullable: true example: 25.29845 longitude: type: number description: The current longitude position of the vessel nullable: true example: 121.217 nautical_speed_knots: type: number description: The current speed of the ship in knots (nautical miles per hour) nullable: true example: 90 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 example: 194 position_timestamp: type: string description: >- The timestamp of when the ship's position was last recorded, in ISO 8601 date and time format nullable: true example: '2023-07-28T14:01:37Z' positions: type: array description: >- An array of historical position data for the vessel. Only included if `show_positions` is true. nullable: true items: type: object properties: latitude: type: number example: 1.477285 longitude: type: number example: 104.535533333 heading: type: number nullable: true example: 51 timestamp: type: string format: date-time example: '2025-05-23T19:14:22Z' estimated: type: boolean example: false 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.