✈️ Air transport

Best practices

Provide weight:
- Total shipment weight directly affects CO₂e emissions and intensity.
Use flight.number and carrier.iata:
- The flight.number field identifies the specific flight taken and retrieves data about the aircraft used (e.g., type, passenger capacity, maximum cargo payload, fuel efficiency) for accurate emissions modeling.
- flight.number accepts either the full combination of the carrier IATA code and flight number or just the flight number alone. If only the flight number is provided, the carrier.iata field must also be populated to retrieve the correct aircraft.
- If flight.number is not provided but carrier.iata is, the system falls back to the carrier's most representative aircraft for the given route.
- Examples
  - In the first example below, flight.number and carrier.iata are provided as separate fields.
  - In the second example, the same request is made, but the carrier IATA code is included within the flight.number. This flexibility allows our API to adapt to the structure of your dataset while offering the same data model accuracy.

{
  "orders": [
    {
      "type": "parcel",
      "weight": 300
    }
  ],
  "transportChainElements": [
    {
      "type": "leg",
      "from": "PVG",
      "to": "AMS",
      "mode": "air",
      "details": {
        "carrier": {
          "iata": "AF"
        },
        "flight": {
          "number": "8448"
        }
      }
    }
  ]
}

{
  "parameters": {
    "orders": [
      {
        "weight": 300,
        "type": "parcel"
      }
    ]
  },
  "co2e": {
    "total": 2010132,
    "wtt": 420028,
    "ttw": 1590105,
    "intensity": 0.75254
  },
  "transportChainElements": [
    {
      "type": "leg",
      "from": {
        "locode": "CNPVG",
        "coordinates": [
          121.80500030517578,
          31.143400192260742
        ],
        "city": "Shanghai Pudong International Airport",
        "country": "China",
        "region": "North East Asia"
      },
      "to": {
        "locode": "NLAMS",
        "coordinates": [
          4.76389,
          52.308601
        ],
        "city": "Amsterdam Airport Schiphol",
        "country": "Netherlands",
        "region": "North Europe"
      },
      "tradeLane": "Asia to-from North Europe",
      "mode": "air",
      "parameters": {
        "details": {
          "flight": {
            "number": "8448"
          },
          "carrier": {
            "iata": "AF"
          }
        }
      },
      "properties": {
        "dataType": "modeled",
        "distance": {
          "sfd": {
            "total": 8903736
          },
          "used": {
            "total": 8998736,
            "source": "daf"
          }
        },
        "model": {
          "name": "gcd-direct-icao"
        },
        "flight": {
          "number": 8448,
          "iataNumber": "AF8448"
        },
        "carrier": {
          "iata": "AF"
        },
        "aircraft": {
          "iata": "772",
          "icao": "B772",
          "manufacturer": "BOEING",
          "model": "Boeing 777-200 pax",
          "type": "passenger"
        },
        "orders": [
          {
            "weight": 300,
            "type": "parcel",
            "co2e": {
              "total": 2010132,
              "wtt": 420028,
              "ttw": 1590105,
              "intensity": 0.75254
            }
          }
        ]
      },
      "co2e": {
        "total": 2010132,
        "wtt": 420028,
        "ttw": 1590105,
        "intensity": 0.75254
      }
    }
  ]
}

{
  "orders": [
    {
      "type": "parcel",
      "weight": 300
    }
  ],
  "transportChainElements": [
    {
      "type": "leg",
      "from": "PVG",
      "to": "AMS",
      "mode": "air",
      "details": {
        "flight": {
          "number": "AF8448"
        }
      }
    }
  ]
}

{
  "parameters": {
    "orders": [
      {
        "weight": 300,
        "type": "parcel"
      }
    ]
  },
  "co2e": {
    "total": 2010132,
    "wtt": 420028,
    "ttw": 1590105,
    "intensity": 0.75254
  },
  "transportChainElements": [
    {
      "type": "leg",
      "from": {
        "locode": "CNPVG",
        "coordinates": [
          121.80500030517578,
          31.143400192260742
        ],
        "city": "Shanghai Pudong International Airport",
        "country": "China",
        "region": "North East Asia"
      },
      "to": {
        "locode": "NLAMS",
        "coordinates": [
          4.76389,
          52.308601
        ],
        "city": "Amsterdam Airport Schiphol",
        "country": "Netherlands",
        "region": "North Europe"
      },
      "tradeLane": "Asia to-from North Europe",
      "mode": "air",
      "parameters": {
        "details": {
          "flight": {
            "number": "AF8448"
          }
        }
      },
      "properties": {
        "dataType": "modeled",
        "distance": {
          "sfd": {
            "total": 8903736
          },
          "used": {
            "total": 8998736,
            "source": "daf"
          }
        },
        "model": {
          "name": "gcd-direct-icao"
        },
        "flight": {
          "number": 8448,
          "iataNumber": "AF8448"
        },
        "carrier": {
          "iata": "AF"
        },
        "aircraft": {
          "iata": "772",
          "icao": "B772",
          "manufacturer": "BOEING",
          "model": "Boeing 777-200 pax",
          "type": "passenger"
        },
        "orders": [
          {
            "weight": 300,
            "type": "parcel",
            "co2e": {
              "total": 2010132,
              "wtt": 420028,
              "ttw": 1590105,
              "intensity": 0.75254
            }
          }
        ]
      },
      "co2e": {
        "total": 2010132,
        "wtt": 420028,
        "ttw": 1590105,
        "intensity": 0.75254
      }
    }
  ]
}

Colliding Parameters

flight.number vs. carrier.iata:
- If both fields are provided and the flightNumber is a combination of the carrier iata and a number, then:
  - flight.number: takes precedence for identifying the aircraft and calculating emissions based on the specific flight.
  - carrier.iata: serves as a fallback when flightNumber is unavailable, calculating emissions based on the carrier's most representative aircraft for the given route.
Aircraft vs. flight.number or carrier.iata:
- If an aircraft is provided alongside flightNumber or scac, it is ignored. The system uses the flight or carrier data to retrieve the most accurate aircraft for the calculation.

Models used

gcd-direct-emissionfactors: default model, applied when only from and to are provided or when the flightNumber and/or carrierIata are not in capacity to retrieve an aircraft information for the modeling of emissions.
gcd-direct-icao: used when a flightNumber and/or carrierIata are provided, providing modeled emissions at the aircraft level.