{ "openapi": "3.1.0", "info": { "title": "Navo Freight Rates API", "version": "1.0.0", "description": "Ocean-freight spot-rate intelligence your code can read. One backend serves freightratesmcp.com: a weekly trade-level rate index, per-lane indicative rates keyed by port-pair (UN/LOCODE), the individual sailing cards behind a lane, and a daily median rate history. Every lane is derived from daily ex-Asia liner rate cards fused with SchedulesMCP reliability. No answer names where a rate came from: every `source` and `provider` value is `navo24` and every source link is `null`, with the same keys always present. Every endpoint takes `Authorization: Bearer ` (or `X-API-Key: `) — one `tmcp_` family key whose org holds an active `freightrates` product entitlement. Successful calls answer back with `X-Usage-*` headers for every cap set on the key. `GET /health` is free and unauthenticated. Browse the same rates free (no key) on the website; the programmatic API and hosted MCP server are on Pro.", "contact": { "name": "FreightRatesMCP", "url": "https://freightratesmcp.com", "email": "hello@freightratesmcp.com" } }, "servers": [ { "url": "https://api.navo24.com/v1/rates", "description": "Navo API" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Index", "description": "Trade-level weekly rate index across the tracked regional lanes." }, { "name": "Lanes", "description": "Per-lane indicative rate, the sailing cards behind it, and daily rate history — keyed by origin/destination UN/LOCODE." }, { "name": "Spot rates", "description": "Multi-modal spot quotes from 55 connected ocean, air, road and rail sources and freight indices." }, { "name": "System", "description": "Unauthenticated service health." } ], "paths": { "/indices": { "get": { "operationId": "getIndices", "tags": [ "Index" ], "summary": "Latest rate index", "description": "The latest weekly rate index for every tracked trade bucket (one row per `line_category_id`), with average 20GP/40GP/40HC, the 40HC median/min/max, sample size and average transit days. This is the trade-level benchmark each lane's `line_premium` is measured against.", "responses": { "200": { "$ref": "#/components/responses/IndexList" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/lane": { "get": { "operationId": "getLane", "tags": [ "Lanes" ], "summary": "Indicative rate for one lane", "description": "The single latest indicative rate card for a port-pair: 20GP/40GP/40HC prices, the representative carrier/vessel/voyage, service mode, transit days and next ETD/ETA. Requires both `pol` and `pod`.", "parameters": [ { "$ref": "#/components/parameters/Pol" }, { "$ref": "#/components/parameters/Pod" } ], "responses": { "200": { "description": "The latest indicative rate for the lane.", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneRate" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/LaneNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/lane/cards": { "get": { "operationId": "getLaneCards", "tags": [ "Lanes" ], "summary": "Sailing cards behind a lane", "description": "Every individual sailing card harvested for the port-pair (the rows the single `/lane` rate is distilled from), ordered by ETD ascending. Each card carries its own carrier, vessel, voyage and prices. `raw` is always `null`. Requires both `pol` and `pod`. Paginated: pass `limit`/`offset` and read `total`/`has_more` to walk every sailing (a dense lane can hold more than one page). Optional `carrier` and `etd_from`/`etd_to` filters narrow the result.", "parameters": [ { "$ref": "#/components/parameters/Pol" }, { "$ref": "#/components/parameters/Pod" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-1000 (the database row ceiling). Defaults to 1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "Row cursor; use with limit to page through total. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "carrier", "in": "query", "required": false, "description": "Case-insensitive exact carrier filter, e.g. MAERSK.", "schema": { "type": "string" } }, { "name": "etd_from", "in": "query", "required": false, "description": "Only sailings departing on or after this date-time (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "etd_to", "in": "query", "required": false, "description": "Only sailings departing on or before this date-time (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "from", "in": "query", "required": false, "description": "Short spelling of etd_from (etd_from wins when both are sent). The word today means the current UTC date, e.g. from=today for upcoming sailings only.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Order of the cards, always ascending: etd (default, soonest first) or a price, cheapest first. Alias: order. An unknown value falls back to etd.", "schema": { "type": "string", "enum": [ "etd", "price_40hc", "price_40gp", "price_20gp" ], "default": "etd" } }, { "name": "compact", "in": "query", "required": false, "description": "true returns the cheapest current card per carrier: from defaults to today, expired prices are left out, and total counts carriers.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A page of sailing cards for the lane (possibly empty), with pagination totals.", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "total", "limit", "offset", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LaneCard" } }, "total": { "type": "integer", "description": "Total cards matching the lane and filters, across all pages." }, "limit": { "type": "integer", "description": "Page size applied (echoes the request, clamped to 1-1000)." }, "offset": { "type": "integer", "description": "Row offset applied (echoes the request)." }, "has_more": { "type": "boolean", "description": "True when offset + returned < total, i.e. a further page exists." } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/lane/spot": { "get": { "operationId": "getLaneSpot", "tags": [ "Lanes" ], "summary": "Spot rates for a lane: FCL and LCL from marketplaces", "description": "Marketplace spot rates for a port-pair, stored in our database and refreshed daily, so the answer is instant. `fcl` holds one entry per offer with the 20ST, 40ST and 40HC prices side by side. `lcl` holds a ladder by shipment size (up to 1, 3 and 10 W/M, where 1 W/M is 1 m3 or 1 tonne, whichever is greater); give `cbm` and `kg` together to get the band that covers a cargo. Each offer carries `covers`: whether origin and destination charges are in the price. Sources do not all quote the same basis, so compare only offers with the same `covers`. Asking for a lane registers it for the daily refresh: a lane never asked before answers `state: queued` with empty lists and is filled within the hour. Prices are USD and indicative, not firm quotes. Requires both `pol` and `pod`.", "parameters": [ { "$ref": "#/components/parameters/Pol" }, { "$ref": "#/components/parameters/Pod" }, { "name": "cbm", "in": "query", "required": false, "description": "Cargo volume in cubic metres, for an LCL estimate. Give with `kg`.", "schema": { "type": "number", "exclusiveMinimum": 0 } }, { "name": "kg", "in": "query", "required": false, "description": "Cargo weight in kilograms, for an LCL estimate. Give with `cbm`.", "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "The stored spot rates for the lane (possibly empty while the first fetch is pending).", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/LaneSpot" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/lane/history": { "get": { "operationId": "getLaneHistory", "tags": [ "Lanes" ], "summary": "Daily rate history for a lane", "description": "The daily median rate curve for a port-pair — one point per day the lane was observed, with the 40HC and 20GP medians and the sample size that day. Ordered by day ascending, so it charts directly. Requires both `pol` and `pod`; an empty array when there is no history.", "parameters": [ { "$ref": "#/components/parameters/Pol" }, { "$ref": "#/components/parameters/Pod" } ], "responses": { "200": { "description": "Daily median history for the lane (possibly empty).", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LaneHistoryPoint" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/quote": { "post": { "operationId": "postSpotQuote", "tags": [ "Spot rates" ], "summary": "Multi-modal spot quotes", "description": "Ranked live and indicative quotes from the connected sources (ocean FCL/LCL, air, road, rail, RoRo, freight indices). Slow marketplaces come back as `pending`: repeat the identical body after `retry_after_s` (never with `no_cache`) until `complete` is true. Indicative quotes are never bookable.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "origin", "destination" ], "properties": { "origin": { "type": "string", "examples": [ "CNSHA" ] }, "destination": { "type": "string", "examples": [ "USHOU" ] }, "shipping_type": { "type": "string", "enum": [ "FCL", "LCL", "BULK", "RORO", "ROAD", "AIR", "RAIL" ] }, "container_type": { "type": "string", "enum": [ "20ST", "40ST", "40HC", "45HC", "20RF", "40RF" ] }, "weight_kg": { "type": "number" }, "volume_cbm": { "type": "number" }, "pieces": { "type": "integer" }, "shipment_date": { "type": "string", "format": "date" }, "road_type": { "type": "string", "enum": [ "FCL", "FTL", "LTL" ] }, "rail_type": { "type": "string", "enum": [ "FCL", "FWL", "FTL", "LWL" ] }, "rate_mode": { "type": "string", "enum": [ "all", "live", "freight_index" ] }, "no_cache": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Quotes, per-source status, `complete` and `pending_providers`. Sources are not named: `provider`, `provider_id` and each `pending_providers` entry read `navo24`, `source_url` is `null`, and `booking_ref` is opaque.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The spot-rate engine did not answer (`upstream_error`) or is misconfigured (`upstream_auth_failed`)." }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/book": { "post": { "operationId": "postSpotBook", "tags": [ "Spot rates" ], "summary": "Booking contacts for a quote", "description": "Releases the booking contacts for a `booking_ref` taken from a quote: the publicly published contacts of the company selling the rate, or the Navo24 contact. Does not place a booking.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "booking_ref" ], "properties": { "booking_ref": { "type": "string", "examples": [ "bk_..." ] } } } } } }, "responses": { "200": { "description": "Contacts with `contact_type` (`vendor` or `navo24`) and `verified_at`. `provider`/`provider_id` read `navo24` and `source_url` is `null`.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The spot-rate engine did not answer (`upstream_error`) or is misconfigured (`upstream_auth_failed`)." }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/providers": { "get": { "operationId": "listSpotProviders", "tags": [ "Spot rates" ], "summary": "Rate source registry", "description": "Every rate source with mode, access type and integration status. Sources are not named: `id` and `name` read `navo24`, links read `null`.", "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "integration", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The provider registry.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The spot-rate engine did not answer (`upstream_error`) or is misconfigured (`upstream_auth_failed`)." }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/providers/{id}": { "get": { "operationId": "getSpotProvider", "tags": [ "Spot rates" ], "summary": "One rate source", "description": "Add `check=1` for a live reachability probe.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "One provider.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "The spot-rate engine did not answer (`upstream_error`) or is misconfigured (`upstream_auth_failed`)." }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Family API key whose org holds an active `freightrates` entitlement, sent as `Authorization: Bearer `. Get a key on the Pro plan at https://freightratesmcp.com." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same family API key, sent as `X-API-Key: ` instead of a bearer token." } }, "parameters": { "Pol": { "name": "pol", "in": "query", "required": true, "description": "Port of loading (origin) UN/LOCODE, case-insensitive.", "schema": { "type": "string", "example": "CNSHA" } }, "Pod": { "name": "pod", "in": "query", "required": true, "description": "Port of discharge (destination) UN/LOCODE, case-insensitive.", "schema": { "type": "string", "example": "NLRTM" } } }, "headers": { "X-Usage-Product": { "description": "The metered product for this key (`freightrates`).", "schema": { "type": "string", "example": "freightrates" } }, "X-Usage-Monthly-Used": { "description": "Calls consumed in the current calendar month. Always present on a successful call.", "schema": { "type": "integer" } }, "X-Usage-Monthly-Reset": { "description": "ISO 8601 timestamp when the monthly counter resets. Always present on a successful call.", "schema": { "type": "string", "format": "date-time" } }, "X-Usage-Daily-Limit": { "description": "Daily call cap, present only when a daily cap is set on the key.", "schema": { "type": "integer" } }, "X-Usage-Daily-Used": { "description": "Calls consumed today, present only when a daily cap is set.", "schema": { "type": "integer" } }, "X-Usage-Daily-Remaining": { "description": "Daily calls remaining, present only when a daily cap is set.", "schema": { "type": "integer" } }, "X-Usage-Daily-Reset": { "description": "ISO 8601 timestamp when the daily counter resets, present only when a daily cap is set.", "schema": { "type": "string", "format": "date-time" } }, "X-Usage-Weekly-Limit": { "description": "Weekly (ISO week) call cap, present only when a weekly cap is set.", "schema": { "type": "integer" } }, "X-Usage-Weekly-Used": { "description": "Calls consumed this ISO week, present only when a weekly cap is set.", "schema": { "type": "integer" } }, "X-Usage-Weekly-Remaining": { "description": "Weekly calls remaining, present only when a weekly cap is set.", "schema": { "type": "integer" } }, "X-Usage-Weekly-Reset": { "description": "ISO 8601 timestamp when the weekly counter resets, present only when a weekly cap is set.", "schema": { "type": "string", "format": "date-time" } }, "X-Usage-Monthly-Limit": { "description": "Monthly call cap, present only when a monthly cap is set.", "schema": { "type": "integer" } }, "X-Usage-Monthly-Remaining": { "description": "Monthly calls remaining, present only when a monthly cap is set.", "schema": { "type": "integer" } }, "X-Usage-Lifetime-Limit": { "description": "Lifetime call cap, present only when a lifetime cap is set.", "schema": { "type": "integer" } }, "X-Usage-Lifetime-Used": { "description": "Calls consumed over the key's lifetime, present only when a lifetime cap is set.", "schema": { "type": "integer" } }, "X-Usage-Lifetime-Remaining": { "description": "Lifetime calls remaining, present only when a lifetime cap is set.", "schema": { "type": "integer" } } }, "responses": { "IndexList": { "description": "Latest rate index rows (one per trade bucket).", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IndexRow" } } } } } } }, "InvalidRequest": { "description": "Both `pol` and `pod` query params are required (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "Unauthorized": { "description": "Missing (`missing_key`), unrecognised (`invalid_key`), revoked (`revoked_key`) or expired (`expired_key`) API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "NotEntitled": { "description": "The key's org does not hold an active `freightrates` entitlement (`not_entitled`). On the MCP surface an org with a spendable Navo Tokens wallet needs no product row; when the wallet cannot pay for the call the code is `insufficient_credits`, `no_wallet`, `trial_expired` or `wallet_inactive`, and `error` also carries `credits_required`, `credits_balance`, `top_up_url` and `packages`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "LaneNotFound": { "description": "No indicative rate exists for the requested port-pair (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "A usage window (daily / weekly / monthly / lifetime) is exhausted (`quota_exceeded`). The `X-Usage-*` response headers show which window and when it resets.", "headers": { "X-Usage-Product": { "$ref": "#/components/headers/X-Usage-Product" }, "X-Usage-Monthly-Used": { "$ref": "#/components/headers/X-Usage-Monthly-Used" }, "X-Usage-Monthly-Reset": { "$ref": "#/components/headers/X-Usage-Monthly-Reset" }, "X-Usage-Daily-Limit": { "$ref": "#/components/headers/X-Usage-Daily-Limit" }, "X-Usage-Daily-Used": { "$ref": "#/components/headers/X-Usage-Daily-Used" }, "X-Usage-Daily-Remaining": { "$ref": "#/components/headers/X-Usage-Daily-Remaining" }, "X-Usage-Daily-Reset": { "$ref": "#/components/headers/X-Usage-Daily-Reset" }, "X-Usage-Weekly-Limit": { "$ref": "#/components/headers/X-Usage-Weekly-Limit" }, "X-Usage-Weekly-Used": { "$ref": "#/components/headers/X-Usage-Weekly-Used" }, "X-Usage-Weekly-Remaining": { "$ref": "#/components/headers/X-Usage-Weekly-Remaining" }, "X-Usage-Weekly-Reset": { "$ref": "#/components/headers/X-Usage-Weekly-Reset" }, "X-Usage-Monthly-Limit": { "$ref": "#/components/headers/X-Usage-Monthly-Limit" }, "X-Usage-Monthly-Remaining": { "$ref": "#/components/headers/X-Usage-Monthly-Remaining" }, "X-Usage-Lifetime-Limit": { "$ref": "#/components/headers/X-Usage-Lifetime-Limit" }, "X-Usage-Lifetime-Used": { "$ref": "#/components/headers/X-Usage-Lifetime-Used" }, "X-Usage-Lifetime-Remaining": { "$ref": "#/components/headers/X-Usage-Lifetime-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "AuthUnavailable": { "description": "Key verification or the entitlement check is temporarily unavailable (`auth_unavailable`). Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "ServerError": { "description": "The rate data could not be read (`server_error`). Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code.", "enum": [ "missing_key", "invalid_key", "revoked_key", "expired_key", "not_entitled", "invalid_request", "not_found", "quota_exceeded", "auth_unavailable", "server_error", "method_not_allowed", "insufficient_credits", "no_wallet", "trial_expired", "wallet_inactive" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "credits_required": { "type": [ "number", "null" ], "description": "Navo Tokens wallet refusals only (insufficient_credits, no_wallet, trial_expired, wallet_inactive; status 402, MCP surface): the Navo Tokens this call costs, or null when the price is not known." }, "credits_balance": { "type": [ "number", "null" ], "description": "Wallet refusals only: the Navo Tokens balance now, or null when there is no wallet." }, "top_up_url": { "type": [ "string", "null" ], "description": "Wallet refusals only: the account page where more Navo Tokens are bought, or null when no link is configured." }, "packages": { "type": "array", "description": "Wallet refusals only: the Navo Tokens packages that can be bought.", "items": { "type": "object", "properties": { "plan": { "type": "string", "examples": [ "starter" ] }, "credits": { "type": "integer", "description": "Navo Tokens in the package.", "examples": [ 7000 ] }, "usd": { "type": "number", "description": "Price in USD.", "examples": [ 69 ] } } }, "examples": [ [ { "plan": "starter", "credits": 7000, "usd": 69 }, { "plan": "growth", "credits": 40000, "usd": 349 }, { "plan": "scale", "credits": 200000, "usd": 1399 } ] ] } } } } }, "IndexRow": { "type": "object", "description": "One trade bucket's latest weekly index row (view `freight_rate_index_latest`).", "additionalProperties": true, "properties": { "line_category_id": { "type": [ "string", "null" ], "description": "Stable id of the trade bucket." }, "line_category": { "type": [ "string", "null" ], "description": "Human trade name, e.g. \"Asia to Europe & Mediterranean\"." }, "week": { "type": [ "string", "null" ], "description": "ISO week the index covers." }, "lane_count": { "type": [ "integer", "null" ], "description": "Distinct lanes in the bucket this week." }, "sample_size": { "type": [ "integer", "null" ], "description": "Rate cards sampled." }, "avg_20gp": { "type": [ "number", "null" ] }, "avg_40gp": { "type": [ "number", "null" ] }, "avg_40hc": { "type": [ "number", "null" ] }, "median_40hc": { "type": [ "number", "null" ] }, "min_40hc": { "type": [ "number", "null" ] }, "max_40hc": { "type": [ "number", "null" ] }, "avg_transit_days": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217, e.g. USD." } } }, "LaneRate": { "type": "object", "description": "The latest indicative rate for a port-pair (view `freight_rate_lane_latest`).", "additionalProperties": true, "properties": { "pol_code": { "type": "string", "description": "Origin UN/LOCODE.", "example": "CNSHA" }, "pol_name": { "type": [ "string", "null" ] }, "pol_country": { "type": [ "string", "null" ] }, "pol_terminal": { "type": [ "string", "null" ] }, "pod_code": { "type": "string", "description": "Destination UN/LOCODE.", "example": "NLRTM" }, "pod_name": { "type": [ "string", "null" ] }, "pod_country": { "type": [ "string", "null" ] }, "pod_terminal": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ], "description": "Representative carrier." }, "vessel": { "type": [ "string", "null" ] }, "voyage": { "type": [ "string", "null" ] }, "route_code": { "type": [ "string", "null" ] }, "service_mode": { "type": [ "string", "null" ], "description": "e.g. direct or transship." }, "is_via": { "type": [ "boolean", "null" ], "description": "Whether the sailing transships." }, "transit_days": { "type": [ "integer", "null" ] }, "etd": { "type": [ "string", "null" ], "format": "date-time", "description": "Next estimated departure." }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "Next estimated arrival." }, "price_20gp": { "type": [ "number", "null" ], "description": "All-in 20GP price." }, "price_40gp": { "type": [ "number", "null" ], "description": "All-in 40GP price." }, "price_40hc": { "type": [ "number", "null" ], "description": "All-in 40HC price." }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217, e.g. USD." }, "line_category": { "type": [ "string", "null" ], "description": "Trade bucket name this lane rolls up to." }, "line_category_id": { "type": [ "string", "null" ] }, "source_updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When this card was last updated." }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When we last saw the card." }, "carrier_logo": { "type": [ "string", "null" ], "description": "Carrier logo URL on a Navo24 host, else `null`." }, "source": { "type": [ "string", "null" ], "description": "Always `navo24`: the rate is a Navo24 rate. Kept for compatibility." } } }, "LaneCard": { "type": "object", "description": "One individual sailing card behind a lane (view `freight_rate_lane_cards`). Superset of LaneRate with the place-of-receipt / place-of-delivery legs.", "additionalProperties": true, "allOf": [ { "$ref": "#/components/schemas/LaneRate" } ], "properties": { "por_code": { "type": [ "string", "null" ], "description": "Place of receipt UN/LOCODE (pre-carriage origin)." }, "pdl_code": { "type": [ "string", "null" ], "description": "Place of delivery UN/LOCODE (on-carriage destination)." }, "valid_to": { "type": [ "string", "null" ], "format": "date", "description": "Rate validity end, when one is stated." }, "raw": { "type": [ "object", "null" ], "description": "Always `null`. Kept for compatibility.", "additionalProperties": true } } }, "LaneSpot": { "type": "object", "required": [ "pol", "pod", "state", "fetched_at", "fcl", "lcl", "notes" ], "properties": { "pol": { "type": "string" }, "pod": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "watching", "capped", "invalid", "unknown" ], "description": "`queued`: registered, first fetch pending (within the hour). `watching`: fetched before." }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "fcl": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "description": "Always `navo24`." }, "carrier": { "type": [ "string", "null" ] }, "prices_usd": { "type": "object", "properties": { "20ST": { "type": [ "number", "null" ] }, "40ST": { "type": [ "number", "null" ] }, "40HC": { "type": [ "number", "null" ] } } }, "transit_days": { "type": [ "integer", "null" ] }, "departure": { "type": [ "string", "null" ], "format": "date" }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "covers": { "type": "string", "enum": [ "origin_destination_included", "ocean_freight_only", "not_stated" ] }, "details": { "type": [ "string", "null" ] }, "badge": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ], "description": "Always `null`." } } } }, "lcl": { "type": "object", "properties": { "reference_kg_per_m3": { "type": "number", "description": "The cargo density the bands were priced at. Heavier cargo can cost more than the band price." }, "bands": { "type": "array", "items": { "type": "object", "properties": { "up_to_wm": { "type": "number" }, "from_usd": { "type": [ "number", "null" ] }, "per_wm_usd": { "type": [ "number", "null" ] }, "offers": { "type": "integer" }, "transit_days": { "type": [ "array", "null" ], "items": { "type": "integer" }, "minItems": 2, "maxItems": 2 }, "valid_until": { "type": [ "string", "null" ], "format": "date" }, "source": { "type": [ "string", "null" ], "description": "`navo24` when the band has an offer, else `null`." }, "covers": { "type": "string", "enum": [ "origin_destination_included", "ocean_freight_only", "not_stated" ] } } } }, "estimate": { "type": [ "object", "null" ], "description": "Present when `cbm` and `kg` were given: the whole band that covers the cargo (not an interpolation).", "properties": { "kind": { "type": "string", "enum": [ "band", "over_largest_band" ] }, "chargeable_wm": { "type": "number" }, "up_to_wm": { "type": "number" }, "from_usd": { "type": "number" }, "heavier_than_reference": { "type": "boolean" } } } } }, "notes": { "type": "array", "items": { "type": "string" } } } }, "LaneHistoryPoint": { "type": "object", "description": "One day of a lane's median rate curve (view `freight_rate_lane_history`).", "additionalProperties": true, "required": [ "day" ], "properties": { "pol_code": { "type": "string", "example": "CNSHA" }, "pod_code": { "type": "string", "example": "NLRTM" }, "day": { "type": "string", "format": "date", "description": "Calendar day of the median." }, "median_40hc": { "type": [ "integer", "null" ], "description": "Median all-in 40HC price that day." }, "median_20gp": { "type": [ "integer", "null" ], "description": "Median all-in 20GP price that day." }, "sample": { "type": [ "integer", "null" ], "description": "Cards sampled that day." } } } } } }