← Journal Use case

Track Air Cargo ETAs with an Air Cargo Tracking API

Use an air cargo tracking API to firm freighter ETAs and trigger customs, dock doors and handling labor on the real arrival, not the schedule.

July 24, 2026 ·

· 11 min read

A unit load device (ULD) sitting on a widebody freighter over the North Atlantic represents committed capital, a customs entry that has to be filed, and a warehouse door that is either ready for it or wasting labor waiting. The gap between "scheduled to land" and "actually on the ground" is where air cargo tracking either saves money or burns it. An air cargo tracking API closes that gap by giving your systems a live, firming ETA for the flight carrying an air waybill (AWB), so customs pre-clearance, ground handling, dock doors and labor are lined up for the real arrival instead of a stale schedule. This guide shows how to build that with FlightNerve's real-time flight data API — pulling a freighter's live position and progress, watching a whole gateway's inbound wave, resolving the operating tail number for charters, and turning a firming ETA into concrete operational triggers.

Why a schedule is not an ETA for air freight

Freight forwarders, customs brokers and 3PLs live on published block times, but a scheduled arrival is a plan, not a promise. A freighter can leave the gate 40 minutes late, ride a jet stream and claw half of it back, get held for weather at the destination, or divert entirely. Each of those events moves the moment your ULD is available for breakdown — and every downstream cost is keyed to that moment.

Guess late and your handling crew stands idle at the dock, your customs entry sits unfiled while the broker waits for wheels-down confirmation, and demurrage starts ticking. Guess that it is on time when it is actually running late and you pull labor onto a door for a plane that is still 200 km out, then pay detention on trucks that showed up early. A cargo flight arrival tracking feed that firms toward the truth as the aircraft approaches lets you commit resources at the right threshold — not on a timetable printed the day before.

FlightNerve exposes this through a handful of REST endpoints. Every call costs one credit, the base URL is https://api.flightnerve.com, and your API key is the first path segment. The free tier gives you 1,000 credits with no card, which is enough to prototype a full gateway board. You can get a free API key and see pricing for production volumes.

The live freighter ETA from /track

The fastest way to answer "where is this flight and when will it land" is the /track endpoint. Give it a flight number and the carrier's IATA code and it returns the airborne aircraft's live position: latitude, longitude, altitude, groundSpeed, heading, the current phase (climb, cruise or descent), a progress value from 0 to 1 along the route, and the operating tail number in regNumber.

curl "https://api.flightnerve.com/YOUR_KEY/track?num=5308&name=FX"

Here is the same call in Node using fetch, wrapped to compute a rough remaining-time signal from progress and phase:

const key = "YOUR_KEY";

async function trackFreighter(num, name) {
  const url = `https://api.flightnerve.com/${key}/track?num=${num}&name=${name}`;
  const res = await fetch(url);
  const data = await res.json();

  if (data.length === 0) {
    // Not airborne yet, or already landed — you pay nothing for this.
    return { airborne: false };
  }

  const f = data[0];
  return {
    airborne: true,
    tail: f.regNumber,
    phase: f.phase,               // climb | cruise | descent
    progress: f.progress,         // 0.0 -> 1.0
    speed: f.groundSpeed,
    source: f.source,             // live | partner | estimated
    position: [f.latitude, f.longitude]
  };
}

Two fields matter most for cargo ops. progress tells you how far along the route the aircraft is, so a value of 0.82 in the descent phase means the ULD is minutes from the ramp. source is your honesty signal: live means a current position, partner is a corroborated position, and estimated means FlightNerve is dead-reckoning the aircraft along its route because of a temporary coverage gap. An estimated position is still useful for planning, but you should treat it as a projection rather than a fix — more on that below.

One detail that keeps your bill honest: if the flight is not in the air, /track returns an empty array []. You pay nothing for a freighter that has not taken off or has already landed, so you can poll a scheduled departure cheaply until it goes airborne.

The whole inbound wave from /airspace

Tracking one AWB is useful. Running a gateway means tracking every freighter converging on your hub at once. The /airspace endpoint gives you a live inbound board: pass inbound= a hub code and it returns every airborne aircraft routed to that airport, each with its callsign, position, distanceKm and etaMinutes — literally how many minutes out each aircraft is.

import requests

KEY = "YOUR_KEY"

def inbound_board(hub):
    url = f"https://api.flightnerve.com/{KEY}/airspace"
    r = requests.get(url, params={"inbound": hub})
    flights = r.json()
    # Sort the wave by minutes-out so the dock plans the closest first.
    return sorted(flights, key=lambda f: f.get("etaMinutes", 9999))

for f in inbound_board("CVG"):
    print(f["callsign"], f["distanceKm"], "km", f["etaMinutes"], "min")

This is the backbone of a "next N freighters inbound" screen for a cargo terminal. Sort by etaMinutes and your ramp supervisor sees the arrival sequence, not a static schedule. You can also scope /airspace by ?airport=CODE, by a radius around a point with ?lat=&lon=&radius=, or by a bounding box with ?bbox=latMin,lonMin,latMax,lonMax — handy if your operation cares about aircraft in a specific approach corridor rather than the whole airport.

Schedule, status and the operating tail from /airline

Live position answers "when," but customs and handling paperwork also need the scheduled block, the current status, and — for freighters and charters — which physical aircraft is operating the flight. The /airline endpoint returns all of it for a given flight number and date.

curl "https://api.flightnerve.com/YOUR_KEY/airline?num=5308&name=FX&date=20260726"

The response carries departure and arrival scheduledTime, estimatedTime and actual times (each as a local string and an ISO-8601 timestamp), plus terminal, gate, airportCode, an aircraft object with code, name and regNumber, and a status of Scheduled, Active, Landed, Arrived, Delayed, Cancelled or Diverted.

The regNumber — the tail number — is why this matters for air freight specifically. The same freighter flight number can be flown by different tails on different days, and charter cargo runs are booked by aircraft. If your customs entry, your handling contract or your dangerous-goods manifest is tied to a specific airframe, the tail on /airline (and confirmed live on /track while it is airborne) is how you match the paperwork to the metal. FlightNerve identifies the tail live during flight, so you can catch a last-minute aircraft swap before the ULD lands. To resolve a hub code into its full name, city, timezone and coordinates, the /airport endpoint takes a ?code= and returns the airport record.

A worked example: ETA firming from 95 to 40 minutes

Say Cargolux flight CV inbound to your gateway is 95 minutes out. Here is how a firming ETA drives the operation, threshold by threshold — the same logic you would automate against /airspace and /track.

95 minutes out (cruise, progress ~0.6): etaMinutes on the inbound board crosses your first threshold. This is the trigger to file the customs entry so pre-clearance is working while the aircraft is still over water. The status on /airline reads Active and the tail matches your manifest — green light to submit.
70 minutes out (top of descent, progress ~0.8): the ETA has firmed within a tighter window. Now you assign the physical dock door and slot the ULD into the breakdown sequence. Because source is live, you can commit the door with confidence rather than penciling it in.
40 minutes out (descent, progress ~0.9): the ETA is now reliable enough to spend money on labor. Call in the handling crew and stage the ground equipment so the ULD moves the moment it is off the aircraft — no idle crew, no aircraft waiting on people.
Wheels down (status flips to Landed, then Arrived): /track returns [] because the flight is no longer airborne, and /airline shows an actual arrival time. That confirmation releases the customs entry and starts the breakdown clock.

Every one of those triggers fired against real aircraft movement, not a schedule. If the same flight had been running late, the thresholds would simply have arrived later and your crew would not have been standing on the dock burning payroll.

Handling diversions, holds and coverage gaps honestly

Not every arrival is clean, and a good air freight ETA API integration plans for the messy ones. Watch the /airline status field: a flip to Diverted means your ULD is going to a different airport entirely and your entire door-and-labor plan for this gateway is void — you want that alert loud and immediate. A Delayed status or an etaMinutes that stops shrinking (an airborne hold) should push your triggers back rather than fire them early.

Coverage gaps deserve the same honesty. When /track reports source: "estimated", FlightNerve is dead-reckoning the aircraft along its known route because there is a temporary gap in live coverage. That projection is good enough to keep a dock plan roughly warm, but you should not spend labor money on an estimated fix alone — wait for source to return to live or partner before committing the crew. Building that distinction into your thresholds keeps you from calling in a shift on a guess.

It is also worth remembering that FlightNerve is not limited to dedicated freighters. A large share of air cargo moves as belly freight on passenger flights, and the same /track, /airspace and /airline calls work identically whether the AWB is on a FedEx 777F or in the hold of a scheduled widebody. One integration covers your whole gateway, freighter and belly alike.

Putting it together for a gateway board

A production cargo dashboard is mostly two loops. A slow loop polls /airspace with inbound= your hub every few minutes to keep the inbound freighter wave current and sorted by etaMinutes. A fast loop calls /track on the specific flights carrying priority AWBs to firm their position and progress, and a daily job hits /airline to pull scheduled blocks, status and tails for the day's expected freighters. Each call is one credit, empty /track results are free, and the free tier's 1,000 credits are enough to run a small gateway board end to end before you commit. When you are ready to scale, review pricing, and if you have not yet, get a free API key to start building.

FAQ

What is an air cargo tracking API?

An air cargo tracking API is a REST service that returns the live position, progress and firming ETA of the flight carrying your freight, so your systems can trigger customs clearance, dock scheduling and handling labor against the real arrival time instead of a static schedule. FlightNerve provides this through its /track, /airspace and /airline endpoints.

How do I track a freighter flight in real time?

Call /track with the flight number and carrier IATA code, for example ?num=5308&name=FX. You get back latitude, longitude, altitude, groundSpeed, phase, a 0-to-1 progress value and the tail number. If the flight is not airborne the call returns an empty array and costs you nothing.

Can I see every cargo flight inbound to a hub at once?

Yes. The /airspace endpoint with inbound= a hub code returns every airborne aircraft routed to that airport, each with distanceKm and etaMinutes. Sort by etaMinutes to build a "next freighters inbound" board for a cargo terminal.

Why does the operating tail number matter for air freight?

The same freighter flight number can be operated by different physical aircraft, and charter cargo is booked by airframe. The regNumber (tail number) on /airline and /track lets you match customs entries, handling contracts and manifests to the exact aircraft, and catch a last-minute swap before the ULD lands.

What happens to my ETA if the flight diverts or hits a coverage gap?

Watch the /airline status field for a Diverted or Delayed flip and treat it as an immediate replan. When /track reports source as estimated, the position is dead-reckoned along the route during a temporary coverage gap — useful for planning, but wait for source to return to live before spending labor money.

Does FlightNerve only cover dedicated freighters?

No. A large share of air cargo travels as belly freight on passenger flights, and the same endpoints work identically whether the AWB is on a dedicated freighter or in the hold of a scheduled widebody, so one integration covers your entire gateway.

How much does it cost to track cargo flights?

Each API call costs one credit, and an empty /track result for a flight that is not airborne is free. The free tier includes 1,000 credits with no card required, enough to prototype a full gateway board. See pricing for production volumes or get a free API key to start.

Build it in minutes — free to start.Get an API key →