{ "openapi": "3.1.0", "info": { "title": "Navo Air Cargo API", "version": "1.0.0", "description": "Air-cargo AWB tracking, live aircraft positions, and air-freight rate quotes. One backend serves two surfaces: aircargomcp.com (AWB tracking + the free prefix oracle + live aircraft positions) and airratesmcp.com (rate quotes). Tracking normalises every airline/platform connector onto an IATA Cargo-IMP milestone shape (RCS → DEP → ARR → RCF → NFD → DLV); the rich geo/route/datetime fields are structure-aligned with the SeaRates Air-Tracking envelope, so a caller who already consumes SeaRates reads this with the same shape. Paid endpoints take `Authorization: Bearer ` (or `X-API-Key: `) — one `tmcp_` family key entitled to the `aircargo` product. The `/prefix/{code}` oracle is free and unauthenticated. AI agents can use the hosted MCP server at https://mcp.aircargomcp.com/mcp instead, with the same key (without one only the resolve_awb_prefix tool answers).", "contact": { "name": "aircargomcp", "url": "https://aircargomcp.com", "email": "hello@aircargomcp.com" } }, "servers": [ { "url": "https://api.navo24.com/v1/air", "description": "Navo API" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Tracking", "description": "AWB tracking and the AWB-prefix airline oracle." }, { "name": "Aircraft", "description": "Live aircraft positions from ADS-B (the air analogue of AIS vessel tracking)." }, { "name": "Rates", "description": "Air-freight rate quotes." } ], "paths": { "/track/{awb}": { "get": { "operationId": "trackAwb", "tags": [ "Tracking" ], "summary": "Track an air waybill", "description": "Resolve an AWB to its current status, route, pieces, weight, ETA and IATA Cargo-IMP milestone events. Any AWB format is accepted (`203-1234 5675`, `20312345675`, `203-12345675`); the 3-digit prefix selects the airline connector. The raw upstream provider body is never returned — provider + freshness metadata is exposed via `data.metadata` instead.", "parameters": [ { "name": "awb", "in": "path", "required": true, "description": "Air waybill number: 3-digit airline prefix + 8-digit serial (last digit is the modulo-7 check digit). Separators and spaces are ignored.", "schema": { "type": "string", "example": "176-12345675" } } ], "responses": { "200": { "description": "Tracking result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AwbTrackingData" } } } } } }, "400": { "$ref": "#/components/responses/BadReference" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The key's org does not hold an active `aircargo` entitlement (`not_entitled`), or, on the MCP surface (`x-aircargo-surface: mcp`), the org's Navo Tokens wallet cannot pay for this call: `insufficient_balance`, `trial_expired`, `wallet_inactive` or `no_wallet`. A wallet refusal keeps its `code`, `message` and status and adds four fields inside `error`: `credits_required` (the price of this call, or null), `credits_balance` (the wallet balance, null when there is no wallet), `top_up_url` (where to buy more tokens, or null) and `packages` (the token packages on sale).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorEnvelope" }, { "$ref": "#/components/schemas/WalletRefusalEnvelope" } ] } } } }, "403": { "description": "The organisation's access has ended (`access_expired`), the product is switched off for it (`product_not_enabled`), or no AWB limit has been set for it yet (`air_limits_not_set`). Contact support; retrying does not help.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "The AWB prefix resolves to a carrier without a wired connector (`unsupported_carrier`), or the airline returned no record for that AWB (`not_found`). `not_found` carries `retry_after` and a `Retry-After` header: 1 hour for the first two misses in a row, 6 hours from the third, 24 hours from the sixth.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The `Idempotency-Key` was already used with a different request (`idempotency_key_reused`), or a request with it is still running (`request_in_progress`, retry shortly).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Your own usage limit is reached: a key usage window (`rate_limited`), the organisation's AWB limit (`quota_exceeded`) or the free trial's AWB allowance (`free_try_exhausted`). See the `X-Usage-*` response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The airline's site failed (`upstream_error`), refused the lookup (`blocked`) or throttled us (`rate_limited`). Temporary; safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Key verification or the entitlement check is temporarily unavailable (`auth_unavailable`), or the API is not accepting requests right now (`auth_unconfigured`). Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/prefix/{code}": { "get": { "operationId": "resolvePrefix", "tags": [ "Tracking" ], "summary": "Resolve an AWB prefix to its airline (free)", "description": "Free, unauthenticated offline oracle. The 3-digit numeric prefix at the head of every air waybill identifies the issuing airline — the air-cargo equivalent of a container BIC prefix. Returns the airline, its public track-and-trace URL, and which shared platform (if any) fronts it.", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "description": "3-digit IATA numeric AWB prefix.", "schema": { "type": "string", "example": "176" } } ], "responses": { "200": { "description": "Airline for the prefix.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AirlinePrefixInfo" } } } } } }, "404": { "description": "Unknown AWB prefix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/aircraft/flight/{flightNumber}": { "get": { "operationId": "aircraftByFlight", "tags": [ "Aircraft" ], "summary": "Live position by flight number", "description": "Live position(s) for the aircraft operating an IATA flight number (e.g. `EK9812` → callsign `UAE9812`), sourced from ADS-B with OpenSky and FR24 fallback. Airborne-only: a parked or out-of-coverage aircraft is a 404.", "parameters": [ { "name": "flightNumber", "in": "path", "required": true, "description": "IATA flight number.", "schema": { "type": "string", "example": "EK9812" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/aircraft/reg/{tail}": { "get": { "operationId": "aircraftByReg", "tags": [ "Aircraft" ], "summary": "Live position by registration / tail number", "description": "Live position(s) for an aircraft by registration (tail number), e.g. `N895FD`. Airborne-only.", "parameters": [ { "name": "tail", "in": "path", "required": true, "description": "Aircraft registration / tail number.", "schema": { "type": "string", "example": "N895FD" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/aircraft/callsign/{cs}": { "get": { "operationId": "aircraftByCallsign", "tags": [ "Aircraft" ], "summary": "Live position by ATC callsign", "description": "Live position(s) for an aircraft by its raw ATC callsign, e.g. `UAE9812`, `FDX9002`. Airborne-only.", "parameters": [ { "name": "cs", "in": "path", "required": true, "description": "Raw ATC callsign.", "schema": { "type": "string", "example": "UAE9812" } } ], "responses": { "200": { "$ref": "#/components/responses/AircraftPositions" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "$ref": "#/components/responses/AircraftNotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/rates/quote": { "post": { "operationId": "quoteRate", "tags": [ "Rates" ], "summary": "Quote an air-freight lane", "description": "Price a lane against the best available rate card. Chargeable weight is `max(gross, volumetric)` where volumetric = `volume_cm3 / 6000`; the applied weight break, net per-kg, surcharges and all-in per-kg are returned. Card source, best-first: live carrier rates (CargoAi) → Freightos FAX region rate → sample card fallback.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirRateQuery" }, "example": { "origin": "HKG", "destination": "FRA", "weight_kg": 250, "service": "general" } } } }, "responses": { "200": { "description": "Rate quote.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AirRateQuote" } } } } } }, "400": { "$ref": "#/components/responses/BadReference" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/NotEntitled" }, "404": { "description": "No rate card for the requested lane.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "503": { "$ref": "#/components/responses/AuthUnavailable" } } } }, "/health": { "get": { "operationId": "health", "summary": "Health check", "security": [], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } } }, "tags": [ "Air Cargo" ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Family API key entitled to the `aircargo` product, sent as `Authorization: Bearer `. Create keys in the dashboard at https://aircargomcp.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." } }, "responses": { "AircraftPositions": { "description": "One or more live aircraft positions (a flight can map to more than one airframe).", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AirAircraftPosition" } } } } } } }, "AircraftNotFound": { "description": "No live position — aircraft not airborne or out of ADS-B coverage (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "BadReference": { "description": "Malformed request: bad AWB (`invalid_reference`) or an invalid rate-quote body.", "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 `aircargo` entitlement (`not_entitled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "RateLimited": { "description": "A usage window (daily / weekly / monthly / lifetime) is exhausted (`rate_limited`), or an upstream airline rate limit was hit. See the `X-Usage-*` response headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "UpstreamError": { "description": "The upstream airline/rate source errored, timed out or blocked the lookup (`blocked` / `rate_limited` / `upstream_error`). Safe to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "AuthUnavailable": { "description": "Key verification or the entitlement check is temporarily unavailable (`auth_unavailable`).", "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": [ "invalid_reference", "unsupported_carrier", "not_found", "blocked", "rate_limited", "upstream_error", "missing_key", "invalid_key", "revoked_key", "expired_key", "not_entitled", "auth_unavailable" ] }, "message": { "type": "string", "description": "Human-readable explanation." } } } } }, "WalletRefusalEnvelope": { "type": "object", "required": [ "error" ], "description": "A Navo Tokens wallet refusal on the MCP surface (402).", "properties": { "error": { "type": "object", "required": [ "code", "message", "credits_required", "credits_balance", "top_up_url", "packages" ], "properties": { "code": { "type": "string", "enum": [ "insufficient_balance", "trial_expired", "wallet_inactive", "no_wallet" ] }, "message": { "type": "string", "description": "Human-readable explanation." }, "credits_required": { "type": [ "number", "null" ], "description": "Navo Tokens this call costs, when known.", "example": 200 }, "credits_balance": { "type": [ "number", "null" ], "description": "The wallet balance now; null when the org has no wallet.", "example": 5 }, "top_up_url": { "type": [ "string", "null" ], "format": "uri", "description": "The account page where more tokens can be bought; null when no link is configured." }, "packages": { "type": "array", "description": "The token packages on sale.", "items": { "type": "object", "required": [ "plan", "credits", "usd" ], "properties": { "plan": { "type": "string", "example": "starter" }, "credits": { "type": "number", "description": "Navo Tokens in the package.", "example": 7000 }, "usd": { "type": "number", "description": "Price in US dollars.", "example": 69 } } } } } } } }, "AirLocation": { "type": "object", "description": "A place (station / airport). Every field is optional; a connector that only knows the IATA code sets just `iata_code`.", "properties": { "iata_code": { "type": [ "string", "null" ], "description": "3-letter IATA airport code.", "example": "HKG" }, "icao_code": { "type": [ "string", "null" ], "description": "4-letter ICAO airport code.", "example": "VHHH" }, "name": { "type": [ "string", "null" ], "example": "Hong Kong International Airport" }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "lat": { "type": [ "number", "null" ] }, "lng": { "type": [ "number", "null" ] }, "timezone": { "type": [ "string", "null" ], "description": "IANA timezone.", "example": "Asia/Hong_Kong" } } }, "AirDateTimes": { "type": "object", "description": "An estimated/actual datetime pair (ISO 8601). `is_actual` says whether the milestone happened; `actual` is the airline's own time of it, null when the airline gave only the schedule.", "properties": { "estimated": { "type": [ "string", "null" ], "format": "date-time" }, "actual": { "type": [ "string", "null" ], "format": "date-time" }, "datetime_precision": { "type": [ "string", "null" ], "enum": [ "datetime", "date", null ], "description": "How precise `actual ?? estimated` is: `date` when the airline gave a day with no hour (sent as that station's midnight, which must not be read as a time of day). Null when the pair is empty." }, "is_actual": { "type": "boolean", "description": "True once the milestone happened: always with `actual`, and also when the airline confirmed it but gave only the scheduled time, which `estimated` then holds (departed on schedule, `actual` null). On a leg it follows the leg's status (left: IN_TRANSIT or ARRIVED; landed: ARRIVED); on the shipment arrival it is true with `actual`, with `eta_is_actual`, or once the status says the shipment is at its destination (arrived, available, delivered), when its time may be only the plan or absent." } } }, "AirStatusCode": { "type": "string", "description": "IATA Cargo-IMP milestone code (unknown codes fall through as a free string).", "enum": [ "BKD", "FOH", "RCS", "MAN", "DEP", "ARR", "RCF", "TFD", "NFD", "AWD", "CCD", "DLV" ] }, "AirEventFamily": { "type": "string", "enum": [ "ACCEPTANCE", "FLIGHT", "DELIVERY", "CUSTOMS" ] }, "AirEvent": { "type": "object", "required": [ "status_code", "event_family", "is_actual", "datetime" ], "properties": { "status_code": { "description": "IATA Cargo-IMP code, or a raw string for codes outside the closed set.", "oneOf": [ { "$ref": "#/components/schemas/AirStatusCode" }, { "type": "string" } ] }, "event_family": { "$ref": "#/components/schemas/AirEventFamily" }, "is_actual": { "type": "boolean", "description": "True once this milestone actually occurred. Some airlines print only the scheduled time of a flight that happened: then `datetimes.estimated` holds it and `datetimes.actual` is null." }, "datetime": { "type": "string", "format": "date-time", "description": "Resolved time (actual ?? estimated); flat, for sorting." }, "datetimes": { "$ref": "#/components/schemas/AirDateTimes" }, "station": { "type": [ "string", "null" ], "description": "IATA 3-letter station code.", "example": "HKG" }, "station_name": { "type": [ "string", "null" ] }, "location": { "oneOf": [ { "$ref": "#/components/schemas/AirLocation" }, { "type": "null" } ] }, "flight_number": { "type": [ "string", "null" ], "example": "EK9812" }, "pieces": { "type": [ "integer", "null" ] }, "weight_kg": { "type": [ "number", "null" ] }, "description": { "type": [ "string", "null" ] } } }, "AirRoute": { "type": "object", "description": "A single leg of the journey (flight or trucking segment). `path` is the great-circle polyline to draw on a map.", "properties": { "order_id": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ], "description": "Upstream leg status (ARRIVED, IN_TRANSIT, …)." }, "booking_status": { "type": [ "string", "null" ], "enum": [ "confirmed", "on_hold", "cancelled", null ], "description": "Whether the airline holds space on this leg: confirmed; on_hold when it has not confirmed the booking (held, requested, waitlisted); cancelled. Null when the airline does not say, or once the leg has flown.", "example": "on_hold" }, "transport_type": { "type": [ "string", "null" ], "description": "PLANE, TRUCK, or an upstream string.", "example": "PLANE" }, "from": { "oneOf": [ { "$ref": "#/components/schemas/AirLocation" }, { "type": "null" } ] }, "to": { "oneOf": [ { "$ref": "#/components/schemas/AirLocation" }, { "type": "null" } ] }, "departure": { "$ref": "#/components/schemas/AirDateTimes" }, "arrival": { "$ref": "#/components/schemas/AirDateTimes" }, "flight_number": { "type": [ "string", "null" ] }, "pieces": { "type": [ "integer", "null" ] }, "weight_kg": { "type": [ "number", "null" ] }, "path": { "type": [ "array", "null" ], "description": "[lat, lng] polyline points.", "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 } } } }, "AwbMetadata": { "type": "object", "description": "Provider + freshness metadata — replaces the raw upstream body in the public response.", "properties": { "status_code": { "type": "string", "description": "Upstream status code (OK, AIRLINE_HASNT_PROVIDE_INFO, …)." }, "airline": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ] }, "iata_code": { "type": [ "string", "null" ] }, "icao_code": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tracking data was last refreshed." }, "from_cache": { "type": "boolean", "description": "Whether this response was served from our cache." }, "cache_expires": { "type": [ "string", "null" ], "format": "date-time", "description": "When our cached copy expires." } } }, "AwbStatus": { "type": "string", "enum": [ "booked", "accepted", "in_transit", "arrived", "available", "delivered", "unknown" ] }, "AwbTrackingData": { "type": "object", "description": "Public AWB tracking payload (the raw/source upstream bodies are stripped at the API boundary). The flat scalar fields are the guaranteed baseline every connector populates; the geo/route/datetime objects are optional enrichment.", "required": [ "awb", "airline_prefix", "airline_iata", "airline_name", "status", "events" ], "properties": { "awb": { "type": "string", "description": "Canonical 11-digit AWB.", "example": "176-12345675" }, "airline_prefix": { "type": "string", "description": "3-digit IATA numeric prefix.", "example": "176" }, "airline_iata": { "type": "string", "description": "2-char IATA airline code.", "example": "EK" }, "airline_name": { "type": "string", "example": "Emirates SkyCargo" }, "status": { "$ref": "#/components/schemas/AwbStatus" }, "origin": { "type": [ "string", "null" ], "description": "IATA origin station code.", "example": "HKG" }, "origin_name": { "type": [ "string", "null" ] }, "origin_location": { "oneOf": [ { "$ref": "#/components/schemas/AirLocation" }, { "type": "null" } ] }, "destination": { "type": [ "string", "null" ], "example": "FRA" }, "destination_name": { "type": [ "string", "null" ] }, "destination_location": { "oneOf": [ { "$ref": "#/components/schemas/AirLocation" }, { "type": "null" } ] }, "pieces": { "type": [ "integer", "null" ], "description": "Total pieces on the AWB." }, "weight_kg": { "type": [ "number", "null" ], "description": "Total gross weight." }, "flight_number": { "type": [ "string", "null" ], "description": "Primary flight number on the AWB." }, "departure": { "$ref": "#/components/schemas/AirDateTimes" }, "arrival": { "$ref": "#/components/schemas/AirDateTimes" }, "eta": { "type": [ "string", "null" ], "format": "date-time", "description": "Resolved arrival, flat: once landed, the first actual landing at the destination (not the delivery); until then actual ?? estimated." }, "eta_is_actual": { "type": "boolean" }, "eta_precision": { "type": [ "string", "null" ], "enum": [ "datetime", "date", null ], "description": "`date` when the ETA is a day with no hour; null when there is no ETA." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AirEvent" } }, "routes": { "type": "array", "description": "Per-leg breakdown with map path, when the source provides it.", "items": { "$ref": "#/components/schemas/AirRoute" } }, "metadata": { "$ref": "#/components/schemas/AwbMetadata" } } }, "AirTrackingPlatform": { "type": "string", "description": "Shared platform fronting the airline's track-and-trace, if any.", "enum": [ "smartkargo", "ibs-icargo", "dhl-aviation", "accelya", "hna-portal2", "ceair" ] }, "AirlinePrefixInfo": { "type": "object", "required": [ "prefix", "iata", "name", "site" ], "properties": { "prefix": { "type": "string", "description": "3-digit IATA numeric prefix.", "example": "176" }, "iata": { "type": "string", "description": "2-char IATA airline code.", "example": "EK" }, "name": { "type": "string", "example": "Emirates SkyCargo" }, "site": { "type": "string", "description": "Public track-and-trace URL (may be a deep link / template).", "example": "https://www.skycargo.com/shipping-services/track-shipments/" }, "platform": { "$ref": "#/components/schemas/AirTrackingPlatform" } } }, "AirAircraftPosition": { "type": "object", "description": "One normalised live aircraft position, mapped off an ADS-B record. Airborne-only.", "required": [ "callsign", "registration", "icao24_hex", "aircraft_type", "lat", "lon", "alt_ft", "ground_speed_kt", "heading", "vertical_rate_fpm", "seen_at" ], "properties": { "callsign": { "type": "string", "description": "ATC callsign, trimmed.", "example": "UAE9812" }, "registration": { "type": [ "string", "null" ], "description": "Tail number, null when not broadcast.", "example": "A6-EFD" }, "icao24_hex": { "type": "string", "description": "24-bit ICAO address (lower-case hex) — the stable aircraft id.", "example": "896180" }, "aircraft_type": { "type": [ "string", "null" ], "description": "ICAO type designator, null when unknown.", "example": "B77L" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "alt_ft": { "type": [ "number", "null" ], "description": "Barometric altitude in feet; 0 on the ground; null when not broadcast." }, "ground_speed_kt": { "type": [ "number", "null" ] }, "heading": { "type": [ "number", "null" ], "description": "True track over ground, degrees 0–359." }, "vertical_rate_fpm": { "type": [ "number", "null" ], "description": "Climb/descent rate, feet per minute (+climb / −descent)." }, "origin_iata": { "type": "string", "description": "Departure airport IATA — only when enriched (ADS-B has no route data)." }, "dest_iata": { "type": "string", "description": "Arrival airport IATA — only when enriched." }, "operator_iata": { "type": "string", "description": "2-char IATA operator code, when resolvable from the callsign." }, "seen_at": { "type": "string", "format": "date-time", "description": "When this position was last observed (ISO 8601 UTC)." } } }, "AirRateService": { "type": "string", "enum": [ "general", "express", "pharma", "perishable", "dangerous_goods" ] }, "AirRateQuery": { "type": "object", "required": [ "origin", "destination", "weight_kg" ], "properties": { "origin": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Origin airport IATA code.", "example": "HKG" }, "destination": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Destination airport IATA code.", "example": "FRA" }, "weight_kg": { "type": "number", "exclusiveMinimum": 0, "description": "Gross weight in kilograms." }, "volume_cm3": { "type": "number", "exclusiveMinimum": 0, "description": "Total volume in cm³, for volumetric/chargeable weight. Omitted → chargeable = gross." }, "service": { "$ref": "#/components/schemas/AirRateService" } } }, "AirRateQuote": { "type": "object", "required": [ "origin", "destination", "chargeable_weight_kg", "applied_band", "net_per_kg", "surcharge_per_kg", "all_in_per_kg", "total_charge", "currency", "source" ], "properties": { "origin": { "type": "string", "example": "HKG" }, "destination": { "type": "string", "example": "FRA" }, "chargeable_weight_kg": { "type": "number", "description": "max(gross, volumetric), where volumetric = volume_cm3 / 6000." }, "applied_band": { "type": "string", "description": "Weight break used.", "enum": [ "MIN", "N", "+45", "+100", "+300", "+500", "+1000" ] }, "net_per_kg": { "type": "number", "description": "Net air rate for the applied band." }, "surcharge_per_kg": { "type": "number", "description": "Fuel + security surcharges per kg." }, "all_in_per_kg": { "type": "number", "description": "net_per_kg + surcharge_per_kg." }, "total_charge": { "type": "number", "description": "max(min_charge, chargeable_weight * all_in_per_kg)." }, "currency": { "type": "string", "description": "ISO 4217.", "example": "USD" }, "airline_iata": { "type": [ "string", "null" ], "description": "Quoting carrier, when carrier-specific." }, "source": { "type": "string", "description": "Where the rate card came from.", "example": "cargoai" } } } } } }