Explore what you can build with the Contrails API and understand how its
endpoints behave.

## Overview

The Contrails API combines large-scale weather data, flight data, and satellite
images with a state-of-the-art computer vision model to produce AI-powered
contrail predictions. These predictions forecast contrail-likely zones and
potential contrail impact for the next 48 hours.

Integrating these predictions into flight planning workflows can help pilots
avoid flying through these regions, preventing the creation of warming
contrails.

To understand these insights of where contrails will form and how warming they
will be, the Contrails API offers forecasts as **grids** and **regions**.

> [!TIP]
> **Tip:** You can also visualize these forecasts using the [ContrailExplorer](https://contrails.webapps.google.com/avoidance).

## Forecasts

The Contrails API offers forecasts as:

- **Grids:** High-fidelity 4D data representing
  [Contrail forcing index values](https://developers.google.com/contrails/v1/forecast-description) on axes of
  latitude, longitude, altitude, and time, in
  [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) format. These grids
  represent the whole globe as a quarter-degree grid, in which latitude and
  longitude steps are 0.25 degrees. Each grid is forecasted for a full hour
  (UTC).

  Contrail forcing index values range from 0, representing a
  location with no significant warming, to 4, representing a location of
  severe contrail warming.

  Grids are recommended for programmatic flight planning, especially for
  rerouting flights.
- **Regions:** Simplified, polygonized version of the forecast, representing
  contrail avoidance regions in GeoJSON multipolygon format.

  Contrail avoidance regions are rated with the same severity levels, but omit
  0 and only start at 1 (light impact).

  Regions are recommended for human flight
  planners who can establish policies based on severity levels and can manually
  reroute flights, typically through vertical deviations (i.e., by adjusting
  flight levels).

  ![ContrailExplorer visualization of forecast regions over parts of Europe, with the selected contrail avoidance region of maximum flight level of 340 and minimum flight level of 310.](https://developers.google.com/static/contrails/images/contrails-explorer-regions.png)

## Authentication

To use the Contrails API, you need an API key and you have to enable the
Contrails API.

For details, follow the [Setting up your environment guide](https://developers.google.com/contrails/v1/getting-started).

## Errors

When using the Contrails API, you can run into the following errors:

| Code | Cause | Error handling |
|---|---|---|
| 400 (invalid requests) | Request with wrong data | Do not automatically retry. This error is caused by problems in code; check that you are using the right parameter format. |
| 404 | Request for a forecast time that hasn't been computed yet | Retry with an [exponential backoff strategy](https://en.wikipedia.org/wiki/Exponential_backoff). |
| 429 | Too many requests (refer to [Usage limits](https://developers.google.com/contrails/v1/limits)) | Retry with exponential backoff. |
| 5XX | Server error | Retry with exponential backoff. |

## Versioning

Major version releases, such as the launch of
[v2](https://developers.google.com/contrails/release_notes#2025-03-31), can introduce behavior incompatible
with previous releases and may require code changes.

Regular updates between major version releases are expected to be
backwards-compatible.

You can read about key updates in the [Contrails API release notes](https://developers.google.com/contrails/release_notes).

## What's next

- To start using the Contrails API, [set your environment up](https://developers.google.com/contrails/v1/getting-started).
- Read the [Contrails API reference documentation](https://developers.google.com/contrails/reference/v2/summary) for detailed guidance on available Contrails API methods.
- Read the [Contrails forecasting overview](https://developers.google.com/contrails/v1/forecast-description) to understand how Contrails API forecasts are computed.