Retrieve detection masks

GET https://contrails.googleapis.com/v2/detections/masks: Get contrail detection masks in NetCDF4 format.

If successful, the response will be a NetCDF of contrail detection masks. Optionally, scantime offsets can also be included in the response.

Note: MTG detection masks are in beta and are subject to change.

Query parameters

Parameters
start_time	string Required. Start time of request. Format: ISO 8601 datetime string Example: 2026-01-20T21:00:00Z
end_time	string Required. End time of request (inclusive). Note that end_time cannot exceed start_time by more than 1 hour. Format: ISO 8601 datetime string Example: 2026-01-20T22:00:00Z
satellite_origin	string Required. Valid values are GOES-WEST-FULL-DISK, GOES-EAST-FULL-DISK, HIMAWARI-FULL-DISK, and MTG-000-FULL-DISK, representing the GOES_WEST, GOES_EAST, Himawari and MTG satellites, respectively. Format: string Example: "GOES-EAST-FULL-DISK"
view	DetectionMaskView Optional. Defaults to DETECTION_MASK_VIEW_UNSPECIFIED. If DETECTION_MASK_VIEW_FULL, will include full disk satellite offsets (in seconds) in the response. Format: see documentation Example: DETECTION_MASK_VIEW_BASIC

Examples

• To retrieve detection masks from a satellite for a specific point of time with scantime offsets:

  response = requests.get(
    url="https://contrails.googleapis.com/v2/detections/masks",
    params={"start_time": "2026-04-10T00:00:00Z",
            "end_time": "2026-04-10T01:00:00Z",
            "satellite_origin": "MTG-000-FULL-DISK"
            "view": "DETECTION_MASK_VIEW_FULL"},
    headers={"x-goog-api-key": API_KEY},
  )
  

  or in CURL:

  curl "https://contrails.googleapis.com/v2/detections/masks?\
  key=API_KEY&\
  start_time=2026-04-10T00:00:00Z&\
  end_time=2026-04-10T01:00:00Z&\
  satellite_origin=MTG-000-FULL-DISK&\
  view=DETECTION_MASK_VIEW_FULL"
  

  When loaded with xarray, this request returns the following dataset:

  Dimensions: (time: 6, y: 5568, x: 5568)
  Coordinates
  Name	Dimensions	Data Type	Values
  time	(time)	datetime64[ns]	2026-04-10T00:00:07 ... 2026-04-10T00:50:07
  y	(y)	float32	5.569e+06 5.567e+06 ... -5.569e+06
  x	(x)	float32	-5.569e+06 -5.567e+06 ... 5.569e+06
  Data variables
  mask	(time, y, x)	float32	0.0 0.0 0.0 0.0 ... 0.0 ...
  scantime_offset	(time, y, x)	float64	nan nan nan nan ... 564. 568. ...
  projection	()	DataArray	+proj=geos +lon_0=0 +h=35786400 +x_0=0 +y_0=0 +a=6378137 +b=6356752.3 +units=m +no_defs

  Note that projection is formatted as the string form of a pyproj.Proj object.

  projection can be used to convert between map x, y coordinates and longitude, latitude coordinates.

DetectionMaskView

Defines the level of detail to return for detection masks.

Enums
DETECTION_MASK_VIEW_UNSPECIFIED	Unspecified view. In practice this is treated as BASIC.
DETECTION_MASK_VIEW_BASIC	Contains detection mask values and satellite projection data.
DETECTION_MASK_VIEW_FULL	Contains detection mask values, satellite projection data, and full disc scantime offsets.