Panvaya Logistics API

The Panvaya REST API delivers normalized supply chain intelligence across global shipping lines. All endpoints return standard JSON payloads and are served under a single base URL.

https://api.panvaya.com/api/v1

Get from zero to your first normalized tracking payload in 3 simple steps:

curl -X POST "https://api.panvaya.com/api/v1/track/ocean" \
  -H "X-API-Key: pv_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{"container": "MSKU8094830"}'

Panvaya is built strictly on open maritime, freight, and data exchange standards. Our API eliminates proprietary carrier payload fragmentation so your engineering team never writes carrier-specific parsers:

Authenticate your requests by including your API key in the X-API-Key header on every call.

X-API-Key: pv_live_your_key_here

Panvaya utilizes transparent, success-only metering. API calls that return an error or 404 NOT_FOUND are never charged.

Check your remaining credit balance anytime via GET /api/v1/usage or in your API Dashboard.

API keys have a default token-bucket rate limit of 10 requests per minute with continuous token refill.

Every API response returns standard rate-limiting and correlation headers:

Sending X-Request-Id with a request is optional. Panvaya generates one if omitted and returns it for support and log correlation.

If throttled, the API responds with HTTP 429 RATE_LIMIT_EXCEEDED and includes a Retry-After: <seconds> header.

Higher rate limits are available for enterprise accounts on request. Submit a request to unlock higher limits.

Publish a Panvaya-hosted ocean tracker on your website using an iframe. Organization administrators configure widgets in Integrations → Web embedding, then copy the installation code. No secret API key is included.

Embedded Ocean Tracking is enabled by default. Its default price is 5 credits per successful search, including cache hits. API, webhook and embedded ocean tracking share the same distinct tracking-reference allowance. Failed searches and page views are unbilled.

Widgets default to an approved-reference allowlist. Open search lets visitors track any supported reference using your balance. Set exact allowed website origins and a daily credit budget. The hosted public page is enabled separately. An allowlist restricts searchable references; it does not authenticate individual visitors. The iframe URL is public and copyable. Website restrictions block unapproved browser frames, but do not authenticate custom HTTP clients.

<iframe src="https://panvaya.com/embed/YOUR_WIDGET_ID" title="Shipment tracking" style="width:100%;height:720px;border:0" loading="lazy" referrerpolicy="strict-origin"></iframe>

For private customer access, enable Require private access and have your backend request a one-time, reference-scoped launch using an existing organization-admin API key. Approved references can also be added or removed through the API. Neither operation consumes tracking credits.

Look up ocean container status, milestone timeline, port pairs, vessel details, and live AIS coordinates. Supply either an ISO container number, Bill of Lading (BOL), or Booking reference.

// Fast lookup maps
const locationMap = new Map(data.locations.map(loc => [loc.id, loc]));
const transportMap = new Map(data.transports.map(t => [t.id, t]));

// Enrich milestones with port and vessel details
const enrichedMilestones = container.events.map(event => ({
  code: event.event_code,
  milestone: event.event_name,
  timestamp: event.event_time,
  isActual: event.actual,
  portName: locationMap.get(event.location_id)?.name,
  unlocode: locationMap.get(event.location_id)?.locode,
  vesselName: transportMap.get(event.transport_id)?.name,
  voyage: transportMap.get(event.transport_id)?.voyage,
}));

curl -X POST "https://api.panvaya.com/api/v1/track/ocean" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"container": "MSKU8094830", "include_route_data": true}'

curl -X POST "https://api.panvaya.com/api/v1/track/ocean" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bol": "MAEU123456789"}'

curl -X POST "https://api.panvaya.com/api/v1/track/ocean" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"bk": "MAEU123456789"}'

Returns all active ocean shipping lines and their Standard Carrier Alpha Codes (SCAC). Pass the carrier SCAC code in shipping_line_scac during tracking to bypass automatic carrier discovery.

curl "https://api.panvaya.com/api/v1/carriers" \
  -H "X-API-Key: pv_live_your_key_here"

Track a full air waybill (AWB). Compact and formatted inputs resolve to the same canonical AWB. Air shares your API credit pool and distinct tracking allowance with Ocean. Each successful response uses the configured Air credit cost; repeated requests for an enrolled AWB do not use another distinct tracking unit in the same cycle. Failed requests are not billed.

curl -X POST "https://api.panvaya.com/api/v1/track/air" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"awb": "044-45428036"}'

The response contains canonical AWB and airline identity, origin and destination airports, planned and actual dates, pieces, weight, shipment status, flight legs, milestones, map route points and waypoints. Missing carrier values remain null. Airport-local dates are preserved.

Success returns the Air object directly, with camelCase field names and airport IATA codes. It does not use the Ocean containers, vessel or shipping-line schema. Errors use the shared errors envelope: 400 for invalid input or unsupported airlines, 404 for no tracking data, 402 for insufficient quota, and 502 UPSTREAM_UNAVAILABLE for airline outages.

Returns supported, available cargo airlines with their names and 3-digit Air Waybill (AWB) prefixes. Send the full AWB to /track/air; its prefix identifies the airline automatically. No separate airline code is needed. This directory requires an API key and is free to call, subject to rate limits.

curl "https://api.panvaya.com/api/v1/airlines" \
  -H "X-API-Key: pv_live_your_key_here"

Search point-to-point departure and arrival schedules between any two UN/LOCODE ports across major ocean carriers with transit times, transshipments, and per-carrier execution statuses. Try sailing schedules

curl -X POST "https://api.panvaya.com/api/v1/schedules/search" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin":"CNSHA","destination":"NLRTM","date":"2025-09-01","weeks":8,"carriers":["MAEU"]}'

Calculate freight carbon emissions (GLEC Framework) between two ports or airports. Returns CO2e in kg and tonnes, car-km equivalents, and trees needed to offset. Try the carbon calculator

curl -X POST "https://api.panvaya.com/api/v1/carbon/calculate" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin": "NLRTM", "destination": "SGSIN", "weightKg": 18000, "mode": "ocean"}'

Estimate embedded product emissions and maritime ETS costs. Uses CARBON_CALCULATOR credits on success. Standalone calculations are read-only; reference factors are planning values, not certified defaults or tax calculations. Responses contain no internal database IDs; API report URLs are null. Downloads use authenticated web endpoints. Try the public CBAM calculator

curl -X POST "https://api.panvaya.com/api/v1/carbon/cbam" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"cnCode":"72083900","netWeightKg":20000,"originCountry":"DEFAULT"}'

Calculate sea distance and estimated transit time between any two ports. Routes through real ocean channels including Suez, Panama, Gibraltar, and Malacca strait. Supports danger-zone avoidance to reroute via the Cape of Good Hope. Try the distance calculator

curl -X POST "https://api.panvaya.com/api/v1/distance-time/calculate" \
  -H "X-API-Key: pv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"origin": "NLRTM", "destination": "SGSIN", "avoidDangerZones": false}'

Retrieve stored vessel master specifications including IMO, MMSI, vessel name, flag, call sign, dimensions, gross tonnage, and TEU capacity.

curl "https://api.panvaya.com/api/v1/vessels?imo=9525338" \
  -H "X-API-Key: pv_live_your_key_here"

Fetch real-time vessel AIS positions, current speed, navigational course, origin/destination ports, ATD, and calculated ETA.

curl "https://api.panvaya.com/api/v1/vessels/position?imo=9525338" \
  -H "X-API-Key: pv_live_your_key_here"

Look up one of the 11 Incoterms 2020 trade terms by code. The response includes the full name, applicable transport mode, risk and cost transfer points, and a 12-stage responsibility breakdown. View the Incoterms guide

curl "https://api.panvaya.com/api/v1/incoterms/FOB" \
  -H "X-API-Key: pv_live_your_key_here"

Monitor real-time global port congestion covering the top 300+ ocean container ports. Returns anchor wait times, berthing durations, approaching vessel queues, and TEU throughput by UN/LOCODE or country code. View the congestion map

curl "https://api.panvaya.com/api/v1/port-congestion?locode=SGSIN" \
  -H "X-API-Key: pv_live_your_key_here"

Returns your organization credit balance, credits used, remaining credits, exact 30-day period reset timestamp, and enabled products with per-call costs. This account endpoint is unbilled.

curl "https://api.panvaya.com/api/v1/usage" \
  -H "X-API-Key: pv_live_your_key_here"

Downloads your organization's success-only billing ledger as a CSV file. Filters by product and date range are optional. This administrative endpoint is unbilled.

curl "https://api.panvaya.com/api/v1/usage/report?productCode=SEA_TRACKING&from=2025-08-01&to=2025-08-07" \
  -H "X-API-Key: pv_live_your_key_here" \
  -o panvaya-api-usage.csv

Public unmetered probe for automated uptime monitors, load balancers, and orchestration health checks. Bypasses API key authentication.

curl "https://api.panvaya.com/api/v1/health"

{
  "status": "operational",
  "service": "panvaya-tracking-api",
  "version": "v1",
  "timestamp": "2026-10-12T07:55:00Z",
  "database": "operational"
}

Errors use a standard JSON envelope with a machine-readable code string. Branch your application logic on the error code, not the error message text.

{
  "errors": [{
    "code": "INVALID_REQUEST",
    "title": "Invalid request",
    "detail": "One of container, bol, or bk is required."
  }]
}

Generate a sandbox test key (prefixed pv_test_) to develop and test in non-production environments. Sandbox requests utilize identical endpoints and schemas, keeping test and production credentials strictly isolated.