On this page, we will explore the data structure used in the Track & Trace API. We'll provide a detailed explanation of the data components, clarify their meanings, and guide you on how to effectively use and interpret this information.

Preamble

To help you understand the information presented below, we have provided a table detailing the fields and their corresponding measurement units:

field name	unit
distance	kilometers
weight	kilograms
volume	cubic meters
duration	hours, minutes, seconds (hours can be absent if flight duration is less than 1 hour)
time	hours, minutes, seconds (hours can be absent if flight duration is less than 1 hour)
carbonEmission	total carbon emission in kilograms

This table serves as a reference guide to help you navigate through the data effectively.

Tracking Update

The "tracking update" refers to the notification you receive when you subscribe to tracking alerts. This notification includes important details about your shipment and its progress. The following sections outline the key components of the tracking update:

Booking/Shipment information - This section serves as the root object encompassing all updates, including tracking events.
Tracking events - This object contains information about specific events (tracking milestones), including associated flights.
Tracking flight - This object provides details about the flight related to a particular event.

Booking/Shipment Information

awb

Provides the airline prefix and air waybill number attached to the consignment note for your shipment.

origin, destination

Displays the IATA standard 3-letter codes for the first origin and the final destination of your shipment's journey.

Shipment Details

Shipment details are shared between three fields of the root object: weight, volume and pieces.

Fields weight, volume and pieces provide details about your shipment as received by the carrier at the first origin.

carbonEmission

Indicates the carbon footprint of your shipment throughout its journey.
To calculate carbon emission we follow IATA's recommended practice in 1678 standard based on exact routing and aircraft code.

status

Reflects the current status of your booking/shipment, such as:

PENDING_DELIVERY - booking is confirmed and carrier is awaiting the shipment to be dropped off before the latest acceptance time (LAT).
IN_TRANSIT - shipment is currently en route from its first origin to its final destination.
AT_DESTINATION - the shipment has arrived at the final destination airport, and a delivery notification has been or will be sent to the agent responsible for delivery.
DELIVERED - shipment has been delivered to the agent, concluding its journey.

Tracking Events

code, description

Displays the code and description of the event currently affecting or that has affected your shipment, such as:

DEP - Departed
BKD - Booked
For more status codes and descriptions, refer to this guide

eventDate

Provides the date and time when the event occurred. Sometimes, this information may be delayed as events need to be logged by the Global Handling Agent (GHA) at the shipment's location.

This date can also serve as the actual departure or arrival date for certain events like departed (DEP) or arrived (ARR) or else.

Please note that this information may not always be posted exactly when the event occurs.
Please take this into consideration when interpreting the data / events.

If the eventDate is later than your current local time, it means that the event "is planned" to happen by the carrier.

eventLocation, eventLocationCoord

Includes the IATA standard 3-letter code and the latitude/longitude of the airport where the event took place. For arrival events (ARR), the location refers to the flight's destination; for others, it will depend on the event and where it takes places.

weight, volume, pieces

Provides details about the shipment at the time of the event.

Split Shipments: If these values differ from the overall shipment details in the root response, it indicates that your shipment has been split between multiple flights. In such cases, the same event (code, description, eventDate, eventLocation) may appear more than once but with different shipment details.

Split Shipment example

First BKD Event (BCN-MAD):
- This event shares the same shipment details as the root response, indicating that the entire shipment was initially booked on a single flight from BCN (Barcelona) to MAD (Madrid).
  Flight Number: 00733
  Weight: 1000 kg
  Pieces: 34
Second and Third BKD Events (MAD-MEX):
- The next two BKD events show the shipment being split for the journey from MAD (Madrid) to MEX (Mexico City). Each event has different details:
  - Second BKD Event: Indicates part of the shipment (600 kg, 17 pieces) is booked on flight 00322.
  - Third BKD Event: Indicates the remaining part (400 kg, 17 pieces) is booked on flight 00373.

This split between flights 00322 and 00373 shows that the shipment will be transported on two separate flights for the route from Madrid to Mexico City. The differing weight and pieces in these events highlight the division of the shipment.

In summary:

The first event (BCN-MAD) corresponds to the entire shipment.
The second and third events (MAD-MEX) show how the shipment is split into two parts for different flights.

{
    "awb": "000-11223345",
    "weight": "1000.0",
    "pieces": "34",
    "origin": "BCN",
    "destination": "MEX",
    "events": [
        {
            "code": "BKD",
            "eventLocation": "BCN",
            "eventLocationCoord": "2.07845998,41.29710007",
            "flight": {
                "number": "00733",
                "origin": "BCN",
                "destination": "MAD",
                "originCoord": "2.07845998,41.29710007",
                "destinationCoord": "-3.56676000,40.49360000",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T20:00:00+01:00",
                "scheduledArrival": "2025-10-25T14:00:00+01:00",
                "carbonEmission": "325.60 kg (est)",
                "distance": "482.74",
                "duration": "32m 10s"
            },
            "weight": "1000.0",
            "pieces": "34",
            "isPlanned": false,
            "distance": "482.74",
            "origin": "BCN",
            "destination": "MAD",
            "time": "32m 10s",
            "flightNumber": "00733",
            "scheduledDepartureDate": "2025-10-25T20:00:00+01:00",
            "carbonEmission": "325.60 kg (est)",
            "originCoord": "2.07845998,41.29710007",
            "destinationCoord": "-3.56676000,40.49360000"
        },
        {
            "code": "BKD",
            "eventLocation": "MAD",
            "eventLocationCoord": "-3.56676000,40.49360000",
            "flight": {
                "number": "00322",
                "origin": "MAD",
                "destination": "MEX",
                "originCoord": "-3.56676000,40.49360000",
                "destinationCoord": "-99.07209778,19.43630028",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T23:15:00+01:00",
                "scheduledArrival": "2025-10-25T03:47:00-06:00",
                "carbonEmission": "955.03 kg",
                "distance": "9065.80",
                "duration": "10h 4m 23s"
            },
            "weight": "600.0",
            "pieces": "17",
            "isPlanned": false,
            "distance": "9065.80",
            "origin": "MAD",
            "destination": "MEX",
            "time": "10h 4m 23s",
            "flightNumber": "00322",
            "scheduledDepartureDate": "2025-10-25T23:15:00+01:00",
            "carbonEmission": "955.03 kg",
            "originCoord": "-3.56676000,40.49360000",
            "destinationCoord": "-99.07209778,19.43630028"
        },
        {
            "code": "BKD",
            "eventLocation": "MAD",
            "eventLocationCoord": "-3.56676000,40.49360000",
            "flight": {
                "number": "00373",
                "origin": "MAD",
                "destination": "MEX",
                "originCoord": "-3.56676000,40.49360000",
                "destinationCoord": "-99.07209778,19.43630028",
                "date": "2025-10-25T00:00:00+01:00",
                "scheduledDeparture": "2025-10-25T15:07:00+01:00",
                "scheduledArrival": "2025-10-25T19:38:00-06:00",
                "carbonEmission": "619.14 kg",
                "distance": "9065.80",
                "duration": "10h 4m 23s"
            },
            "weight": "400.0",
            "pieces": "17",
            "isPlanned": false,
            "distance": "9065.80",
            "origin": "MAD",
            "destination": "MEX",
            "time": "10h 4m 23s",
            "flightNumber": "00373",
            "scheduledDepartureDate": "2023-11-25T15:07:00+01:00",
            "carbonEmission": "619.14 kg",
            "originCoord": "-3.56676000,40.49360000",
            "destinationCoord": "-99.07209778,19.43630028"
        }
    ],
    "status": "PENDING_DELIVERY",
    "originCoord": "2.07845998,41.29710007",
    "destinationCoord": "-99.07209778,19.43630028",
    "carbonEmission": "1899.78 kg (est)",
    "distance": "9548.54",
    "time": "10h 36m 34s"
}

additionalInformation

Provides additional details, if available, about the shipment's tracking, such as:

receivedFromName - Name of the agent who dropped off the shipment.
notificationToName - Name of the agent notified that the shipment is ready for delivery.
transferredToCarrier - Name of the carrier that will take over the shipment, if it has been transferred. This can occur in cases like interline bookings or an overbooked aircraft. Please note, we are not responsible for transfers between carriers.

isPlanned

A flag indicating whether the event is planned. Airlines and carriers often have the ability to provide information about certain events in advance, such as bookings, departures, or arrivals. These anticipated events are marked as "planned" because they are scheduled based on the airline's flight plan.

However, since planned events may change due to various factors (e.g., delays, cancellations, changes in flight routes), it's crucial to verify the details regularly. For example, a carrier might schedule a booking or flight in advance, but the actual occurrence of this event could differ. Always confirm the information until the event is completed to ensure accuracy.

origin, destination, originCoord, destinationCoord

Provides the IATA standard 3-letter code and latitude/longitude of the origin and destination airports for the event.

Overall Event's Flight Information

distance and time - The distance traveled by the flight from origin to destination and the estimated duration.
flightNumber and scheduledDepartureDate - Information to identify the flight and its scheduled departure.
carbonEmission - Details the carbon footprint of your shipment for this specific event, following IATA's recommended practice in 1678 standard based on exact routing and aircraft code.

eventUlds

This object contains two fields: pieces, uld.

Provides the information about the number of ULD (pieces) and the ULD type (uld) if the event contains any ULD.

trackingFlight

This object embedded in the tracking events provides information about the flight linked to the event (if there is one).

Tracking Flight

The tracking flight is a special object in our Tracking API that provides details about the flight linked to an event affecting your shipment.

Please note that we rely on the flight information provided by the carrier, so there may be instances where some flight details are missing for specific AWBs.

number, origin, destination, date

These fields provide overall information about your flight.

number - Provides the number to identify the flight.
origin and destination - Provide the IATA standard 3 letter code about the origin and destination of the flight.
date - Provides flight's departure date. In some cases, the time is also available.

originCoord, destinationCoord

Provides the latitude and longitude of the flight's origin and destination airports.

scheduledDeparture, actualDeparture, scheduledArrival, actualArrival

Detail the scheduled and actual departure and arrival times for the flight.

"Scheduled" indicates the planned time, while "Actual" indicates when the flight actually departed or arrived.

Based on the event type you may not have the same information available. For example, for a departed (DEP) event, you may have the actualDeparture without the actualArrival, and for an arrived (ARR) event, you may have the actualArrival without the actualDeparture.

Note that airlines may not always provide actual departure or arrival information; in such cases, you can use the eventDate as a backup, but we cannot guarantee its accuracy if it's not provided by the airline.

carbonEmission, distance, duration

Provide additional details about the flight linked to the event:

carbonEmission - Indicates the carbon footprint of your shipment for the flight (similar to carbonEmission at the tracking event level).
distance - Provides the distance traveled by the flight from origin to destination (same as the distance at the tracking event level).
duration - Provides the total duration of the flight from origin to destination.

flightULDs

This object contains two fields: pieces, uld.

Provides the information about the number of ULD (pieces) and the uld type (uld) if the flight contains any ULD (same as eventULDs at tracking event level).

Tracking Error Messages

Below are the common tracking error responses and the descriptions with more details.

Invalid Body

Error Name: ErrInvalidBody
HTTP Code: 400
Description: Indicates that the request body is malformed or does not meet the expected structure or inputs.

FlightUUID Doesn't Exist

Error Name: ErrInvalidFlightUUID
HTTP Code: 400
Description: The provided FlightUUID is not found in the system.

Invalid AWB Format. Please Check AWB

Error Name: ErrInvalidAWB
HTTP Code: 400
Description: The provided AWB format is invalid or does not comply with the required standards.

Internal Server Error

Error Name: ErrInternalServerError
HTTP Code: 500
Description: An unexpected error occurred on the server.

Already Subscribed

Error Name: ErrAlreadySubscribed
HTTP Code: 400
Description: The url or email is already subscribed to the AWB or FlightUUID.

All Emails Are Already Subscribed

Error Name: AllEmailsSubscribed
HTTP Code: 400
Description: Indicates that all provided emails are already subscribed for the specific AWB or FlightUUID.

Maximum 5 Emails Allowed

Error Name: ErrMaximumFiveEmails
HTTP Code: 400
Description: The request exceeds the allowed limit of 5 email addresses at a time.

Unauthorized Request

Error Name: ErrUnauthorized
HTTP Code: 401
Description: The client is not authorized to perform this operation.

Missing Key Parameter(s)

Error Name: ErrMissingKeyParams
HTTP Code: 400
Description: One or more required paraters are missing in the request.

AWB Length Not Equal to 12

Error Name: ErrInvalidAWBLength
HTTP Code: 400
Description: The provided AWB does not have the required length of 12 characters.

Invalid AWB. Wrong Check Digit

Error Name: ErrInvalidAWBCheckDigit
HTTP Code: 400
Description: The check digit for the provided AWB is invalid.