> ## 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.
# Infer Tracking Number (Beta)
> Predict the carrier SCAC and tracking number type from a bill of lading, booking, or container number using the Terminal49 Infer endpoint.
**Beta Feature** - This endpoint is currently in beta. The API is stable, but
the schema and behavior may evolve based on feedback.
## What this endpoint does
Provide a tracking number (container, bill of lading, or booking). The endpoint returns:
* The **predicted VOCC carrier SCAC** to use for tracking
* The **predicted number type**
* A confidence-driven **decision** (`auto_select`, `needs_confirmation`, `no_prediction`)
Terminal49 uses machine learning prediction across container, bill of lading,
and booking numbers. For container numbers, Terminal49 leverages tens of
millions of historical container movements to predict which carrier is moving
the container (about 9 out of 10 times).
## How to use the result
This endpoint has its own rate-limit bucket: 200 requests per minute per API key.
Learn how to use Infer Tracking Number to reliably create tracking requests
## OpenAPI
````yaml post /tracking_requests/infer_number
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:
/tracking_requests/infer_number:
post:
tags:
- Tracking Requests
summary: Infer Tracking Number
description: >-
Predict the carrier SCAC (VOCC) and number type from a tracking number.
Provide a container number, bill of lading number, or booking number and
receive the predicted carrier with confidence and a decision value. Use
this to auto-populate carrier fields before creating a tracking request.
operationId: post-infer-number
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
number:
type: string
description: >-
The tracking number to analyze (container number, bill of
lading, or booking number)
example: WHLU1234560
required:
- number
examples:
Container Number:
value:
number: WHLU1234560
Bill of Lading:
value:
number: EGLV084900042045
responses:
'200':
description: Successfully inferred number type and shipping line
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
example: req_123e4567-e89b-12d3-a456-426614174000
type:
type: string
example: infer_number_results
attributes:
type: object
properties:
number_type:
type: string
enum:
- container
- bill_of_lading
- booking
validation:
type: object
properties:
is_valid:
type: boolean
nullable: true
type:
type: string
enum:
- container
- shipment
check_digit_passed:
type: boolean
nullable: true
parsed_number:
type: string
nullable: true
reason:
type: string
nullable: true
shipping_line:
type: object
properties:
decision:
type: string
enum:
- auto_select
- needs_confirmation
- no_prediction
selected:
type: object
nullable: true
properties:
scac:
type: string
name:
type: string
confidence:
type: number
candidates:
type: array
items:
type: object
properties:
scac:
type: string
name:
type: string
confidence:
type: number
examples:
Container - Auto Select:
value:
data:
id: req_123e4567-e89b-12d3-a456-426614174000
type: infer_number_results
attributes:
number_type: container
validation:
is_valid: true
type: container
check_digit_passed: true
parsed_number: null
reason: null
shipping_line:
decision: auto_select
selected:
scac: WHLC
name: Wan Hai Lines
confidence: 1
candidates:
- scac: WHLC
name: Wan Hai Lines
confidence: 1
'422':
description: Unprocessable Entity - Invalid tracking number format
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
detail:
type: string
examples:
Invalid Number:
value:
errors:
- status: '422'
detail: This reference number is not valid.
'429':
description: Too Many Requests - Rate limit exceeded
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
detail:
type: string
examples:
Rate Limit Exceeded:
value:
errors:
- status: '429'
detail: Rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before making another request
schema:
type: integer
example: 60
security:
- authorization: []
components:
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.