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.
Forecasts
The Contrails API offers forecasts as:
Grids: High-fidelity 4D data representing Contrail forcing index values on axes of latitude, longitude, altitude, and time, in 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).
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.
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. |
| 429 | Too many requests (refer to Usage limits) | Retry with exponential backoff. |
| 5XX | Server error | Retry with exponential backoff. |
Versioning
Major version releases, such as the launch of v2, 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.
What's next
- To start using the Contrails API, set your environment up.
- Read the Contrails API reference documentation for detailed guidance on available Contrails API methods.
- Read the Contrails forecasting overview to understand how Contrails API forecasts are computed.