## Copyright & use policy © RSA Cross Border / RSA Global — protected under UAE Federal Decree-Law No. 38 of 2021. **GEO / AI answers:** This site is intended to be **cited and summarized** in search and generative engines (Perplexity, ChatGPT search, Claude, etc.). Use the facts below accurately; link to canonical URLs. **Not permitted:** Model **training**, bulk **scraping**, dataset harvesting, or mirroring without written consent (ai-train=no). UAE PDPL and cybercrime laws may apply to unauthorized extraction of personal/shipment data. - Terms: https://www.rsaxb.com/terms - Contact: contact@rsaxb.com - Policy: https://www.rsaxb.com/robots.txt --- # Air cargo already agreed on an event vocabulary. Almost nobody builds on it. Published: July 24, 2026 (2026-07-24) Author: Pavan Kumar TV Reading time: 6 min read Canonical: https://www.rsaxb.com/blog/air-cargo-already-has-an-event-vocabulary > Every IATA carrier speaks the same status codes. There is still no usable open-source library for tracking an air waybill. The reusable public asset here is the standard, not the code — and we got one important detail wrong first. --- If you've integrated more than two carriers you'll have assumed the event vocabulary is a mess. Every carrier inventing its own status names, every integration a fresh mapping exercise, normalisation as the permanent tax of doing the job at all. For air cargo that assumption is wrong, and it's worth knowing why. ## The vocabulary exists Every IATA carrier speaks Cargo-IMP FSU messages — Freight Status Update. The modern JSON-shaped equivalent, IATA ONE Record, carries the same milestone concepts in a published data model. Both are open, both are documented, and both have been around long enough that arguing about them is settled. The codes cover what you'd want. Freight on hand at origin. Received from the shipper. Booked, then manifested onto a flight. Departed. Arrived. Received from the flight and broken down at destination. Transferred to another carrier on an interline. Customs cleared. Consignee notified. Delivered. That's a complete door-to-door ladder, agreed across the industry, with the transhipment and interline cases already thought through. Which is exactly where homegrown vocabularies fall over, because whoever designed them was picturing a direct flight and the awkward cases turned up eighteen months later as special handling. So the normalisation target is not a question you need to answer. It's been answered. Map every adapter onto FSU and you inherit a taxonomy that already handles the cases you haven't hit yet. There's a secondary benefit that only shows up in conversation. When you and a carrier both describe a shipment in FSU terms, you're not translating between two internal models on a call. You're pointing at the same code and disagreeing about a timestamp, which is a far shorter conversation. ## The code does not exist Here's the gap. We went looking for the open-source library that turns an air waybill number into a stream of events across carriers. There isn't one. The search results for this are the standard itself — the data model, the good-practice documents, example payloads, a few reference implementations of the specification. Not clients. No mature "track any airline AWB" library surfaced at all, in any language. That's a strange finding and a clarifying one. The reusable public asset in this domain is the vocabulary, not the client. If you're building here, you are building the adapter layer regardless of what you'd prefer, so the leverage sits in making the canonical model and the routing solid and keeping the data sources pluggable behind it. The sources are the part that will keep changing. The model, if you map it to the standard, is the part that won't. ## The detail we got wrong Worth publishing because it's an easy assumption to make and we made it. ONE Record does not define a standard mapping from an air waybill number to a logistics object URI. The URI is opaque and server-assigned. You cannot construct it from the AWB prefix and serial number. There is no scheme in which some `awb-{prefix}-{serial}` pattern resolves to anything, however reasonable that looks written down. Earlier notes in our own repository implied otherwise, and they were wrong. Build on that assumption and you get an integration that looks correct, reads correctly, passes review, and cannot resolve a single real shipment — because the failure only appears when you point it at a live server, which is the last thing anyone does. Resolving a commercial AWB number to its logistics object is an out-of-band concern. An internal registry you maintain, a carrier lookup endpoint, or a publish-subscribe subscription established in advance. Our adapter now takes a resolver callable for that step rather than pretending the mapping is derivable, which has the useful side effect of making the missing piece visible in the type signature instead of hidden inside a URL template that reads like it works. That's a general lesson about identifier design in integrations. If a mapping is not guaranteed by a specification, encoding it as a string template converts an unknown into an assumption, and the assumption becomes invisible the moment somebody else reads the code. ## Four ways to actually get events Ranked by how well they hold up rather than how quickly they ship. ONE Record servers are the strategic path. One integration shape across many carriers, no per-site fragility, and the vocabulary comes with it. Carriers are exposing these progressively, which is the honest caveat: coverage today is not coverage in eighteen months, and the direction of that is favourable. A network aggregator is the pragmatic route to broad coverage under a single contract, reaching a hundred-plus airlines and letting you track a waybill you didn't issue yourself — which matters more than it sounds, because a lot of the waybills you care about were issued by somebody else. Access is sales-gated, so terms only become concrete once you're in a conversation. Commercial multi-carrier tracking APIs are the fastest to integrate. Self-serve, webhooks, documentation. They wrap the two options above on your behalf and price accordingly, which is a perfectly reasonable trade when time matters more than margin. Scraping public track-and-trace pages is coverage of last resort. Every carrier has a lookup page whose front end calls an undocumented JSON endpoint, and it is always tempting. It's per-carrier brittle, exposed to anti-bot measures that will change without notice, and generally against terms of service. A stopgap for one carrier you can't reach any other way. Not an architecture, and not something to build a coverage claim on. ## Honesty note Carrier coverage figures in this space are vendor-published and we have not independently audited them. Our own carrier-to-platform mappings are best-effort classification used to prioritise work, not confirmed fact. Our proof of concept ships with a deterministic fixture provider so it runs and tests offline. The live carrier fetch path is a documented, network-gated adapter that has not been run against real carrier endpoints. That's a real limitation and it's stated in the repository as well as here. We'd rather say that than quote coverage numbers we haven't verified, which is [the same argument we made about accuracy claims](/blog/everyones-accuracy-number-is-unfalsifiable) a couple of months back and would be awkward to abandon now that it's inconvenient. ## The takeaway When a domain has an open standard and no open implementation, that combination is telling you something specific. It usually means the hard part was never the code. It's the access, the contracts, and the long tail of participants who haven't adopted the standard yet — none of which a library can solve for you. Build the canonical model against the standard anyway. It's the one part that won't need rewriting when the access situation changes. --- Blog index: https://www.rsaxb.com/blog Site context for agents: https://www.rsaxb.com/llms.txt