Retrieve a forecast grid

GET https://contrails.googleapis.com/v2/grids: Get a grid of contrail forecasts.

If successful, the response will be a NetCDF of contrail forcing values.

Query parameters

Parameters
time	string Required. Time of request. Format: ISO 8601 datetime string OR Unix epoch integer Example: 2026-01-20T21:00:00Z
bbox[]	number Optional. Boundaries of region to return. Format: [lng_min, lat_min, lng_max, lat_max] Example: [-40, 20, 20, 60]
aircraftType	string Optional. Aircraft code. Format: 4-character ICAO aircraft type code Example: A320
flightLevel[]	integer Optional. Flight levels to return. If no flight level is specified, then all flight levels are included. Format: Flight levels in hectofeet; [270, 280, 290, 300, 310, 320, 330, 340, 350, 360, 370, 380, 390, 400, 410, 420, 430, 440] Example: [270, 280, 290, 300]
format	string Optional. Requested format. Passing in a value other than 'netcdf4' will raise an UNIMPLEMENTED error since polygons are not supported.
aircraftClass	string Optional. Aircraft class. Currently, only default is supported.
data[]	string Optional. This field specifies which data variables to include in the response. It can handle one or multiple data variables. If this field is empty or not provided, it defaults to ["contrails"]. Example: ["contrails", "expected_effective_energy_forcing"]

Examples

• To retrieve the default global contrail grid for a specific point in time:

  response = requests.get(
    url="https://contrails.googleapis.com/v2/grids",
    params={"time": 2026-01-27T12:00:00Z},
    headers={"x-goog-api-key": API_KEY},
  )
  

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

  Dimensions: (longitude: 1441, latitude: 721, flight_level: 18, time: 1)
  Coordinates
  Name	Dimensions	Data Type	Values
  longitude	(longitude)	float32	-180.0 -179.8 ... 179.8 1...
  latitude	(latitude)	float32	-90.0 -89.75 -89.5 ... 8...
  flight_level	(flight_level)	int16	270 280 290 300 ... 41...
  time	(time)	datetime64[ns]	2026-01-28T20:00:00
  forecast_reference_time	(time)	datetime64[ns]	2026-01-27T08:00:00
  Data variables
  contrails	(longitude, latitude, flight_level, time)	float32	0.0 0.0 0.0 0.0 ... 0.0 ...
  Attributes
  inference_pipeli...		contrails.forecast-pipeline_20260115.02_p0
  api_version :		contrails.api-service_20260125.00_p0
  aircraft_class :		default

• To retrieve a grid limited to a specific geographic boundary and filtered for a specific aircraft type, with time specified as a Unix epoch integer:

  response = requests.get(
    url="https://contrails.googleapis.com/v2/grids",
    params={"time": 1769508160,
            "bbox": [-40, 20, 20, 60],
            "aircraftType": "A320"
            },
    headers={"x-goog-api-key": API_KEY},
  )
  

• To retrieve a grid limited to a subset of flight levels and a specific region with the contrails and expected_effective_energy_forcing layers:

  response = requests.get(
    url="https://contrails.googleapis.com/v2/grids",
    params={"time": 2026-01-27T12:00:00Z,
            "bbox": [-10, 40, 10, 55],
            "flightLevel": [300,310,320,330],
            "data": ["contrails", "expected_effective_energy_forcing"]
            },
    headers={"x-goog-api-key": API_KEY},
  )