Attributions

Attributed contrail segments for a specific list of flights.

Data format

Requests for attributed contrails contains data with the following structure:

JSON representation 
{
  "attributions": [
    {
      object (Attribution)
    }
  ]
}
Fields
attributions[]

object (Attribution)

A list of attributions one for each resource name specified in the BatchGetAttributionsRequest.names. The order of attributions in this list will match the order of names in the BatchGetAttributionsRequest. If a flight was not found, the corresponding Attribution message in the response will only have the name field populated, while flightDetails and contrail will be empty.

Attribution

Represents an aggregated contrail event for a specific flight summarizing all attributed contrail segments (e.g., total kilometers and energy).

JSON representation 
{
  "name": string,
  "flightDetails": {
    object (FlightDetails)
  },
  "contrail": {
    object (ContrailAttributes)
  },
  "segments": [
    {
      object (SegmentAttribution)
    }
  ]
}
Fields
name

string

Identifier. The resource name of the flight.

Format:

carriers/{carrier}/flightNumbers/{flightNumber}/departureDates/{departure_date}/departureAirports/{departure_airport}

Components:

  • {carrier}: 2-character IATA carrier code (e.g., "AA", "UA").
  • {flightNumber}: 1-4 digit flight number (e.g., "123").
  • {departure_date}: Flight departure date in YYYY-MM-DD format.
  • {departure_airport}: 3-letter IATA airport code (e.g., "JFK", "LHR").
flightDetails

object (FlightDetails)

The detail information for this flight.
contrail

object (ContrailAttributes)

Aggregated contrail attributes for the entire flight. This sums up the contrail attributes from all attributed segments.

State interpretation (within a found flight):

  • If present: Contrail analysis was performed. The fields inside ContrailAttributes indicate the results (e.g., lengthMeters > 0 means contrails were attributed).
  • If absent: Contrail analysis could NOT be performed for this flight.
    • This is typically due to insufficient input data (e.g., missing weather data or flight path uncertainty).
    • This does NOT mean no contrails were formed, only that a determination couldn't be made.
segments[]

object (SegmentAttribution)

Per-segment contrail attributions. Each entry represents a distinct time interval of the flight to which contrail(s) were attributed.

FlightDetails

Defines the full set of flight information returned in the response.

JSON representation 
{
  "carrier": string,
  "flightNumber": integer,
  "departureTime": string,
  "icao24": string,
  "originAirport": string,
  "destinationAirport": string,
  "callSign": string,
  "analyzedFlightDistanceMeters": integer
}
Fields
carrier

string

IATA carrier code of the flight (e.g. "AA").
flightNumber

integer

Flight number of the flight (e.g. "123").
departureTime

string

Departure date in the origin airport's timezone; int: unix epoch OR str: ISO 8601.
icao24

string

ICAO 24-bit aircraft address
originAirport

string

IATA origin airport code.
destinationAirport

string

IATA destination airport code.
callSign

string

Callsign of the aircraft. This field preferentially contains the callsign used in Air Traffic Control (ATC) communications. If the specific ATC callsign is not available or is the same as the standard flight designator, this field holds the standard flight designator (typically a combination of airline code and flight number for commercial flights).
analyzedFlightDistanceMeters

integer

Distance of the flight analyzed, in meters.

ContrailAttributes

Represents the contrail attributes for a flight or flight segment.

JSON representation 
{
  "lengthMeters": integer,
  "effectiveEnergyForcingJoules": string
}
Fields
lengthMeters

integer

The length, in meters, of the subset(s) of the flight path to which contrails were attributed. This is calculated as the great circle distance between the flight waypoints.
effectiveEnergyForcingJoules

string (int64 format)

Total effective contrail energy forcing, in joules. This is currently calculated based on climatological averages and is subject to change.

SegmentAttribution

Represents contrail attribution for a specific time segment of a flight.

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "contrail": {
    object (ContrailAttributes)
  },
  "detectionEvidences": [
    {
      object (ContrailDetectionEvidence)
    }
  ]
}
Fields
startTime

string (Timestamp format)

Start time of the flight segment to which contrails are attributed. This timestamp is in UTC epoch seconds.
endTime

string (Timestamp format)

End time of the flight segment to which contrails are attributed. This timestamp is in UTC epoch seconds.
contrail

object (ContrailAttributes)

Contrail attributes for this specific segment.
detectionEvidences[]

object (ContrailDetectionEvidence)

Individual satellite contrail detections that provide evidence for the attribution to this flight segment.

ContrailDetectionEvidence

Details of a single satellite observation of a contrail.

JSON representation 
{
  "observationTime": string,
  "observedLengthMeters": integer,
  "dataSource": enum (DataSource)
}
Fields
observationTime

string (Timestamp format)

Time when the satellite image was taken in which the contrail was detected. This is typically the start time of the scan. This timestamp is in UTC epoch seconds.
observedLengthMeters

integer

The observed end-to-end length of the linear contrail feature in meters, as detected in the satellite image specified by observationTime. This length can differ from the lengthMeters in SegmentAttribution.contrail because:

  • The contrail may have evolved (e.g., spread, lengthened, etc.) in the atmosphere between formation and observation.
  • The attribution algorithm was only able to confidently attribute a portion of this contrail to this flight.
dataSource

enum (DataSource)

Output only. The source of the satellite data used for this detection.

DataSource

The source of the satellite data used for contrail detection. Additional values may be added in the future.

Currently, GOES East and MTG are available satellite data outputs. GOES East based attributions have production-level quality, while MTG-based attributions are still in the Beta phase and actively undergoing quality improvements.

Enums
DATA_SOURCE_UNSPECIFIED Unspecified data source.
GOES_EAST_FULL_DISK Data from GOES-East full disk scans.
GOES_WEST_FULL_DISK Data from GOES-West full disk scans.
MTG_000_FULL_DISK Data from MTG-000 full disk scans.
HIMAWARI_FULL_DISK Data from Himawari full disk scans.