API v1 — stable

FreightLanesAI API

Structured ocean freight intelligence for lane analysis, route planning, commercial exposure, and disruption signals. Integrate freight data into your TMS, quoting system, or internal tools.

Quickstart

Send your first lane intelligence request in under a minute:

Create a free account — 50 analyses per month included
Go to API Keys and create your first key
Call the API with your key in the Authorization header

curl

curl -X POST https://api.freightlanesai.com/api/v1/lane-intelligence \
  -H "Authorization: Bearer fli_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "originCountryCode": "CN",
    "destinationCountryCode": "IL",
    "originPortUnlocode": "CNSHA",
    "destinationPortUnlocode": "ILHFA",
    "commodityQuery": "lithium batteries",
    "hsCode": "850760",
    "shipmentDate": "2026-04-15",
    "includeAlternatives": true,
    "includeCommercialExposure": true
  }'

Authentication

All API requests must include your API key as a Bearer token in the Authorization header:

header

Authorization: Bearer fli_your_api_key_here

Keep your API key secret. Never expose it in client-side code or public repositories.

Endpoints

POST

/api/v1/lane-intelligence

Country-to-country or port-to-port lane intelligence. Requires origin and destination country codes.

POST

/api/v1/route-intelligence

Detailed port-to-port route analysis. Origin and destination UNLOCODE are required.

GET

/api/v1/openapi.json

OpenAPI 3.1 specification. No authentication required.

Request schema

Both endpoints accept the same JSON request body:

Field	Type	Required	Description
originCountryCode	string	Yes	ISO 3166-1 alpha-2 origin country (e.g. "CN")
destinationCountryCode	string	Yes	ISO 3166-1 alpha-2 destination country (e.g. "IL")
originPortUnlocode	string	Route only	UN/LOCODE of origin port (e.g. "CNSHA")
destinationPortUnlocode	string	Route only	UN/LOCODE of destination port (e.g. "ILHFA")
commodityQuery	string	No	Plain-language commodity (e.g. "lithium batteries")
hsCode	string	No	HS code 4 or 6 digits (e.g. "850760")
shipmentDate	string	No	Expected shipment date YYYY-MM-DD
includeAlternatives	boolean	No	Include alternative route suggestions (default: true)
includeCommercialExposure	boolean	No	Include commercial exposure analysis (default: true)
timeRangeDays	number	No	7 / 30 / 90 / 180 — market signal window (default: 30)

Response schema

Successful responses return structured JSON with these top-level fields:

json

{
  "requestId": "req_abc123...",
  "version": "v1",
  "generatedAt": "2026-04-01T10:00:00Z",
  "input": { ... },
  "lane": { "laneCode": "CN-IL", "corridorCode": "...", "priorityLane": true },
  "commodity": { "normalizedName": "Lithium Batteries", "hsCode": "850760", ... },
  "marketIntelligence": { "direction": "rising", "confidence": "medium", ... },
  "routeIntelligence": { "corridorLabel": "...", "pol": {...}, "pod": {...}, "restrictions": [...], ... },
  "disruptions": [...],
  "commercialExposure": { "exposureLevel": "High", "exposureScore": 72, ... },
  "fuelSurchargeOutlook": { "currentBafUsd": 280, "forecastBafUsd": 310, ... },
  "meta": { "confidence": "medium", "quota": { "used": 12, "limit": 50, "remaining": 38 } }
}

Error codes

Status	Error	Meaning
200	—	Success. Search credit consumed.
400	ValidationError	Invalid request parameters. Credit not consumed.
401	Unauthorized	Missing or invalid API key.
422	InsufficientData	No intelligence signals for this lane. Credit not consumed.
429	QuotaExceeded	Monthly quota exhausted. Upgrade plan or wait for reset.
500	InternalError	Analysis failed. Credit not consumed.

Code examples

JavaScript / TypeScript

typescript

const response = await fetch('https://api.freightlanesai.com/api/v1/lane-intelligence', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer fli_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    originCountryCode: 'CN',
    destinationCountryCode: 'IL',
    commodityQuery: 'lithium batteries',
    shipmentDate: '2026-04-15',
  }),
})
const data = await response.json()
console.log(data.commercialExposure?.exposureLevel) // "High"

Rate limits & quota

Free

50 / month

Starter

150 / month

$19

Growth

500 / month

$50

Pro

5,000 / month

$200

Quotas reset on the 1st of each month. Validation failures and server errors do not consume your quota.

View full pricing ↗