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 an empty ContrailAttributes message is present, it means that analysis was performed but both lengthMeters and energy forcing evaluated to zero.
  • 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 in YYYYMMDD format.
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 derived by extracting effective radiative forcing from 4D gridded CoCiP forecast outputs and linearly interpolating them. This methodology 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)
    }
  ],
  "attributionMethod": enum (AttributionMethod),
  "longGapInterpolation": boolean,
  "waypointAttributions": [
    {
      object (WaypointAttribution)
    }
  ]
}
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.
attributionMethod

enum (AttributionMethod)

Output only. The method used for attributing contrails to this segment (e.g., CoCiP model or direct observation).
longGapInterpolation

boolean

Output only. True if the segment flight path was generated by interpolating over a long ADS-B data gap (>5 minutes).
waypointAttributions[]

object (WaypointAttribution)

Output only. Per-waypoint contrail attributes mapped across this 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.

WaypointAttribution

Represents contrail attributes for a specific waypoint in a flight segment.

JSON representation 
{
  "time": string,
  "contrailAttributes": {
    object (ContrailAttributes)
  }
}
Fields
time

string (Timestamp format)

The time at the waypoint in UTC epoch seconds.
contrailAttributes

object (ContrailAttributes)

The contrail attributes mapped at this specific waypoint.

AttributionMethod

Defines the specific procedure or methodology used to make the attribution.

Enums
ATTRIBUTION_METHOD_OBSERVATION Attribution derived strictly by matching against satellite contrail detections.
ATTRIBUTION_METHOD_COCIP Attributions relying strictly on physics-driven CoCiP modeling.
ATTRIBUTION_METHOD_OBSERVATION_ENHANCED_COCIP

Hybrid attribution combining CoCiP model forecasts adjusted by satellite detections.

  • With Detections: If detectionEvidences is present, the contrail was predicted and confirmed by observation, receiving enhanced warming weight.
  • Without Detections: If detectionEvidences is missing, the contrail was predicted but not observed, so the calculated warming is discounted.
ATTRIBUTION_METHOD_UNSPECIFIED Unspecified method.

Notes

Each DataSource has different bounds used for processing observational-based views, outlined below: Satellite coverage bounding boxes (flat mercator view)

License

The data exposed by the ContrailWatch Attributions API is licensed under CC BY-NC 4.0.