Observations Data Service

Contrails.org hosts APIs surfacing various datasets with contrail observation, detection and flight attribution data. These datasets are currently based on geospationary satellite imagery, but will extended to other observation sources in the future. These endpoints are still experimental and are not to be viewed as complete datasets.

The Observations Data Service provides the following endpoints:

Below we provide a description of data processing levels and brief descriptions of the endpoint signatures. See the OpenAPI documentation for more detailed descriptions.

Levels

Observational datasets are subject to processing at various levels ranging from Level 0 (L0) to Level 4 (L4). L0 products are datasets obtained directly from source data providers. Higher-level products are derived from L0 products interpreted values that provide direct information about contrails.

Our data processing levels are inspired by the NASA Data Processing Levels, but are not exactly the same. We’ve done our best to keep the meaning of these processing levels consistent with EOSDIS standards.

Not all dataset sources will have all levels. This may be due to either:

  1. Lack of availability: a provider has not yet released a dataset at that level for a given source.

  2. Incompatible leveling semantics: the definition of a level is incompatible with the nature of data from a given source.

Level 0 (L0)

Data provided directly by the source data provider. Contrails.org does not cache and/or preserve L0 data. Note that source data providers may use their own level system, and datasets that are L0 in this API’s leveling system may be a higher level in the source data provider’s leveling system.

For instance, GOES brightness temperatures used for geostationary contrail detections are L0 in this API’s leveling system (because they are available directly from a source data provider) but L2 in GOES’ own leveling system.

Level 1 (L1)

Derived variables at the same resolution and location and in the same coordinate reference system as L0 source data. Examples:

  • Output from a contrail detection model that assigns a contrail detection confidence to each pixel in a satellite image.

Level 2 (L2)

Derived properties of contrail instances. L2 data uses the same coordinate reference system as underlying L0 and L1 data. Examples:

  • Output from a contrail linearization model that extracts line-like representations of detected contrail segments from detection masks.

Level 3 (L3)

L1 and L2 variables and properties provided on a uniform space-time grid or in a unified coordinate reference system. Contrails.org does not provide a data product at this level at this time. Examples:

  • Contrail line segments mapped from the source native coordinate reference system to WGS84.

Level 4 (L4)

Outputs from models or analyses of (possibly multiple) lower-level data sources. Examples:

  • Flight attributions that associate L3 contrail instances with portions of ADS-B flight trajectories.

  • Value-added products that provide meteorological properties interpolated from forecasts or reanalysis to locations of L3 contrail instances.

Contrails.org GOES L1 detections

Return contrail detection confidences for a given GOES disk image. Available on 10 minute intervals matching the GOES scan frequency.

Signature

GET /v1/observations/contrails-org/goes/L1/detections?time={iso_timestamp_naive} HTTP/2

Host:

api.contrails.org

Headers:

x-api-key: {contrails-api-key}

Parameters:
iso_timestamp_naive

timezone naive ISO-compliant timestamp. Floored to nearest 10min interval.

Response:

Content-Type: application/x-netcdf

Contrails.org GOES L2 segments

Returns a list of line-like objects representing contrails extracted from the corresponding L1 GOES detections.

Line-like objects are in WKT format in GOES’ CRS. No assertion is made about a line-like object belonging 1:1 with a flight instance.

Signature

GET /v1/observations/contrails-org/goes/L2/segments?time={iso_timestamp_naive} HTTP/2

Host:

api.contrails.org

Headers:

x-api-key: {contrails-api-key}

Parameters:
iso_timestamp_naive

timezone naive ISO-compliant timestamp. Floored to nearest 10min interval.

Response:

Content-Type: application/json

Google Geospatial Attributions L4

Returns a list of observations and attributions for a given flight. This is data reformatted from the Google Contrail Watch API.

The attributions make a best effort inference of which contrail segments are attributed to a given flight along with their calculated energy forcing. The observations are the linked satellite images that were used to determine the contrail segments attributed to the flight.

Signature

GET /v1/observations/google/geostationary/L4/attributions?flight=AA~6441~2025-05-11~SAF&flight=AA~6441~2025-05-12~SAF HTTP/2

Host:

api.contrails.org

Headers:

x-api-key: {contrails-api-key}

Parameters:
flight (string; repeated);

format: {carrier}~{flight_number}~{departure_date}~{departure_airport_iata} example: AA~6441~2025-05-11~SAF

Response:

Content-Type: application/json