Method: batchGetAttributions

Gets multiple contrail attributions by flight information.

If successful, the response will be a list of contrail attributions.

HTTP request

GET https://contrails.googleapis.com/v2/{parent=attributions}:batchGet

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The parent resource shared by all attributions being retrieved. Format: attributions

Query parameters

Parameters
names[]

string

Required. The resource names of the flights to retrieve. A maximum of 100 names can be provided in a single request.

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").

Request body

The request body must be empty.

Response body

Response which contains the attributed contrails for attributions.batchGet.

If successful, the response body 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 could not 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; 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.

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.