Google Contrails Forecasts

Requires a valid Google API key, enabled for the Contrails API.

References

• Google Contrails API

import cartopy.crs as ccrs
import matplotlib.pyplot as plt
import pandas as pd

from pycontrails.datalib.google_forecast import GoogleForecast, Severity

gf = GoogleForecast(
    # The API provides hourly forecasts, e.g. +24h into the future.
    time=(pd.Timestamp.now() + pd.Timedelta("24h")).floor("h"),
    variables=(Severity),  # Also supports EffectiveEnergyForcing.
    # key="YOUR_API_KEY",  # Optional if GOOGLE_API_KEY env var is set
)

met = gf.open_metdataset()
met

MetDataset with data:

<xarray.Dataset> Size: 75MB
Dimensions:                  (longitude: 1441, latitude: 721, level: 18, time: 1)
Coordinates:
  * longitude                (longitude) float64 12kB -180.0 -179.8 ... 180.0
  * latitude                 (latitude) float64 6kB -90.0 -89.75 ... 89.75 90.0
  * level                    (level) float64 144B 154.7 162.4 ... 329.3 344.3
  * time                     (time) datetime64[ns] 8B 2026-02-05T16:00:00
    flight_level             (level) int16 36B 440 430 420 410 ... 290 280 270
    forecast_reference_time  (time) datetime64[ns] 8B 2026-02-04T15:00:00
    air_pressure             (level) float32 72B 1.547e+04 ... 3.443e+04
    altitude                 (level) float32 72B 1.341e+04 ... 8.23e+03
Data variables:
    contrails                (longitude, latitude, level, time) float32 75MB ...
Attributes:
    inference_pipeline_version:  contrails.forecast-pipeline_20260129.02_p0
    api_version:                 contrails.api-service_20260203.02_p0
    aircraft_class:              default
    provider:                    Google
    dataset:                     Contrails Forecast
    product:                     forecast

xarray.Dataset

• Dimensions:
  • longitude: 1441
  • latitude: 721
  • level: 18
  • time: 1
• Coordinates: (8)
  • longitude
    (longitude)
    float64
    -180.0 -179.8 ... 179.8 180.0

    array([-180.  , -179.75, -179.5 , ...,  179.5 ,  179.75,  180.  ],
          shape=(1441,))

  • latitude
    (latitude)
    float64
    -90.0 -89.75 -89.5 ... 89.75 90.0

    array([-90.  , -89.75, -89.5 , ...,  89.5 ,  89.75,  90.  ], shape=(721,))

  • level
    (level)
    float64
    154.7 162.4 170.3 ... 329.3 344.3

    units :

    hPa

    long_name :

    Pressure

    positive :

    down

    array([154.735056, 162.353861, 170.347799, 178.735341, 187.535866, 196.769709,
           206.458205, 216.623742, 227.289409, 238.41928 , 249.98641 , 262.00382 ,
           274.4848  , 287.442907, 300.891973, 314.846102, 329.319679, 344.327369])

  • time
    (time)
    datetime64[ns]
    2026-02-05T16:00:00

    array(['2026-02-05T16:00:00.000000000'], dtype='datetime64[ns]')

  • flight_level
    (level)
    int16
    440 430 420 410 ... 300 290 280 270

    array([440, 430, 420, 410, 400, 390, 380, 370, 360, 350, 340, 330, 320, 310,
           300, 290, 280, 270], dtype=int16)

  • forecast_reference_time
    (time)
    datetime64[ns]
    2026-02-04T15:00:00

    array(['2026-02-04T15:00:00.000000000'], dtype='datetime64[ns]')

  • air_pressure
    (level)
    float32
    1.547e+04 1.624e+04 ... 3.443e+04

    standard_name :

    air_pressure

    long_name :

    Air pressure

    units :

    Pa

    array([15473.506, 16235.386, 17034.78 , 17873.533, 18753.586, 19676.97 ,
           20645.82 , 21662.375, 22728.941, 23841.928, 24998.64 , 26200.383,
           27448.48 , 28744.291, 30089.197, 31484.61 , 32931.97 , 34432.74 ],
          dtype=float32)

  • altitude
    (level)
    float32
    1.341e+04 1.311e+04 ... 8.23e+03

    standard_name :

    altitude

    long_name :

    Altitude

    units :

    m

    array([13411.2, 13106.4, 12801.6, 12496.8, 12192. , 11887.2, 11582.4,
           11277.6, 10972.8, 10668. , 10363.2, 10058.4,  9753.6,  9448.8,
            9144. ,  8839.2,  8534.4,  8229.6], dtype=float32)

• Data variables: (1)
  • contrails
    (longitude, latitude, level, time)
    float32
    0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0

    array([[[[0.],
             [0.],
             [0.],
             ...,
             [0.],
             [0.],
             [0.]],
    
            [[0.],
             [0.],
             [0.],
             ...,
             [0.],
             [0.],
             [0.]],
    
            [[0.],
             [0.],
             [0.],
             ...,
    ...
             ...,
             [0.],
             [0.],
             [0.]],
    
            [[0.],
             [0.],
             [0.],
             ...,
             [0.],
             [0.],
             [0.]],
    
            [[0.],
             [0.],
             [0.],
             ...,
             [0.],
             [0.],
             [0.]]]], shape=(1441, 721, 18, 1), dtype=float32)

• Attributes: (6)

  inference_pipeline_version :

  contrails.forecast-pipeline_20260129.02_p0

  api_version :

  contrails.api-service_20260203.02_p0

  aircraft_class :

  default

  provider :

  Google

  dataset :

  Contrails Forecast

  product :

  forecast

severity_da = met.data["contrails"].isel(time=0).max(dim="level")
p = severity_da.plot(
    x="longitude",
    y="latitude",
    cmap="Reds",
    subplot_kws=dict(projection=ccrs.PlateCarree(), transform=ccrs.PlateCarree()),
    figsize=(10, 4),
)
p.axes.coastlines()
plt.title("Maximum contrail severity over all flight levels");