Release Notes

7 January 2025

Features

3 January 2025

Features

  • Update the meteorology sources used in the Contrails API. See the Meteorology section for details.

Fixes

  • Fix some 500 errors that were caused by outdated meteorology data.

20 Nov 2024

Breaking changes

  • Updates to the v1/grids and v1/regions endpoints, migrating from path params to query params.

  • Updates to the netCDF response object, migrating forecast_reference_time from a dataset attribute to a non-indexed coordinate.

  • Updates to the geoJSON response object, adding resource-identifying metadata to features[0].properties.

Additional context can be found in the v1 API interface contract spec.

16 Oct 2024

Features

  • Add notebook for Contrail Forecast API /v1.

  • Revise existing notebook documentation to reflect /v0 and /v1 differences.

10 Oct 2024

Breaking changes

11 Jul 2024

Features

28 May 2024

Features

  • Release of the v1 API routes, including /v1/grids and v1/regions, for gridded netcdf and geojson polygons, respectively. These data are backed by the new API Preprocessor system.

15 February 2024

Fixes

  • Fix issue in which intermediate range ERA5 data is not available in the backend. Previously, a 422 error was occasionally encountered when attempting to call the /grid/cocip or /grid/issr with a request time several weeks into the past. Now HRES data is used in these cases when ERA5 data is not available. See Meteorology for more details.

2 February 2024

Features

26 January 2024

Fixes

  • Fix issue in flight string parsing.

16 January 2024

Breaking changes

  • Remove the ability to pass an API key via a query parameter. Instead, API keys must always be included in the x-api-key header. See the Get Started Documentation for an example.

  • Remove the /auth/validate-key endpoint. There are no longer any /auth endpoints.

  • The URL variable defined in each example notebook is now set by an environment variable. The end user should set this to https://api.contrails.org/v0 when running the notebooks.

19 December 2023

Features

14 November 2023

Fixes

  • Address several internal server errors causing 500 errors.

3 November 2023

Breaking changes

  • Ignore the met_source parameter on GET endpoints and the met_source field on POST endpoints. This parameter was added in `v0.10.0`_ and is now deprecated. For forecast and near to realtime /trajectory and /grid requests, HRES data is used. For historical /trajectory and /grid requests, ERA5 data is used. The choice of met data is no longer configurable by the user. Remove the met_source schema. No longer support running models with historic HRES data.

  • Change the AvailabilityResponse served by the /grid/availability endpoint. Previously this endpoint specified availability by endpoint and by met source. Now, this endpoint only specifies availability by endpoint. The new response takes the following form:

    {
  "cocip" : [
    "2022-01-01T00:00:00Z",
    "2023-10-31T17:00:00Z"
  ],
  "issr" : [
    "2018-01-01T00:00:00Z",
    "2023-11-01T06:00:00Z"
  ],
  "pcr" : [
    "2018-01-01T00:00:00Z",
    "2023-11-01T06:00:00Z"
  ],
  "sac" : [
    "2018-01-01T00:00:00Z",
    "2023-11-01T06:00:00Z"
  ]
}

  • Remove the met_source field on both responses. Include four additional fields:

    • met_source_provider

    • met_source_dataset

    • met_source_product

    • met_source_forecast_time

    on all responses. The first three are always included in the response. The last is only included if forecast data (ECMWF HRES) is used.

Features

  • Extend the availability of HRES-based /trajectory models and /grid/issr, /grid/sac, and /grid/pcr endpoints 58 - 65 hours into the future.

  • Run all HRES-based /trajectory models and /grid/issr, /grid/sac, and /grid/pcr endpoints on model level weather forecasts. This provides a more accurate representation of the vertical atmosphere.

  • Improve the runtime of the /grid/availability endpoint. This endpoint now takes less than 1 second to run. Previously, this endpoint took 5 - 7 seconds.

  • Alias the Trajectory.altitude field with altitude_ft. This allows for better parity with pycontrails.

  • Allow passing a threshold=0 query parameter to the /grid/cocip endpoint. This constructs polygons around nonzero CoCiP predictions. Previously, this query parameter was required to be positive. Now it only must be non-negative.

Fixes

  • Ensure the forecast_time is correctly included in /grid/cocip responses. Previously this was frequently missing.

  • Ensure a consistent time format when serving exceptions involving timestamps.

18 October 2023

Fixes

  • Issue a 422 error if a degenerate bounding box is provided in /grid endpoints. Previously a 500 error could be encountered.

16 October 2023

Fixes

  • Issue a 422 error if a string time field contains NaN values. This is now handled in both /trajectory payloads and in /grid query parameters. Previously a 500 error was encountered.

12 October 2023

Breaking changes

  • Remove the /auth/list-keys and /auth/generate-key endpoints. Shift towards one key per user_id moving forward.

5 October 2023

Fixes

  • Internal improvements

20 September 2023

Features

21 July 2023

Features

  • Add a saf_blend parameter to the Trajectory schema. If provided, the jet fuel is assumed to be a blend of Sustainable Aviation Fuel (SAF) and Jet A-1 according to the provided proportion. The default value is 0.0 (i.e., 100% Jet A-1). Providing a value of 1.0 will assume 100% SAF. See the pycontrails SAFBlend source code for more details.

12 July 2023

Fixes

  • Fix bug occasionally causing internal server errors.

11 July 2023

Breaking changes

  • Any provided flight_id field on a /trajectory request body is now required to be a string or an array of strings. Previously, this field was allowed to be an integer.

Fixes

  • Address corner case in polygon computation that caused an internal server error.

Features

  • Upgrade to Pydantic v2. This may have inadvertently introduced breaking changes into the API. Please report any issues of non-backwards compatibility.

30 June 2023

Breaking changes

  • Issue a 422 error in /trajectory endpoints if the payload includes an aircraft_mass field with any increasing values. This field is required to be decreasing because the fuel mass flow rate is computed as the difference between consecutive values.

Features

21 June 2023

Fixes

  • Internal improvements

4 May 2023

Breaking changes

  • If included, require the met_source parameter on a trajectory to be one of "HRES" or "ERA5". Previously this field was case-insensitive and allowed "hres" and "era5" as valid values. This field is now a case-sensitive enum (if provided).

  • No longer compute the trajectory CoCiP model as part of the /trajectory/profile endpoint. The ProfileResponse object now only contains a profile field as well as a few other metadata fields. Use the /trajectory/cocip endpoint separately if waypoint-by-waypoint CoCiP values are also needed.

Features

  • Allow the /trajectory/profile computation to operate in a grid mode by setting mode=grid in the request body. In this mode, a less accurate but more performant algorithm is used compute the vertical profile: instead of calculating CoCiP over the vertical slice defined by the trajectory, this slice is instead interpolated against precomputed CoCiP values. See the comparison notebook for a comparison of the two modes of computation.

3 May 2023

Fixes

  • When possible, infer fuel flow from "aircraft_mass" if the later is provided in /trajectory payloads.

  • If a "tas" field is provided in /trajectory payloads, use this value for true airspeed. Previously, the "tas" field was ignored.

1 May 2023

Fixes

  • Fix bug occasionally occurring in /trajectory/cocip endpoint introduced in `v0.15.3`_ when a contrail advects out of the met domain.

  • Fix bug occurring when HRES met data is used in /trajectory/cocip endpoint.

28 April 2023

Features

Fixes

  • Address some issues in polygon algorithms that previous caused internal server errors.

11 April 2023

Fixes

  • Fix edge case in polygon calculation that created an internal server error.

10 April 2023

Fixes

  • Remove deprecated aliases /auth/validate and /auth/generate. The full /auth/validate-key and /auth/generate-key endpoints should be used instead.

4 April 2023

Breaking changes

  • Remove the level_type query parameter on all /grid endpoints. This parameter was added in `v0.2.0`_ and deprecated in `v0.14.0`_. All gridded products are now only computed at flight levels.

Features

  • Enable flight_level query parameter on all /grid endpoints. Previously this was only available on the /grid/cocip endpoint. See `v0.14.0`_.

  • Faster backend polygon computation.

  • Serve Redoc documentation at https://api.contrails.org/redoc.

21 March 2023

Better support for polygon simplification.

Features

  • Include a flight_level query parameter on the /grid/cocip endpoint for vertical down-selection. This parameter can take several forms: - A single flight level (e.g., flight_level=300) - A comma-separated list of flight levels (e.g., flight_level=300,320,340) - A list of flight levels (e.g., flight_level=[300,320,340]) If not specified, gridded data for all available flight levels are included in the response. In a future release, this parameter will be supported in each /grid endpoint. In addition, the level_type parameter will be removed in the future.

  • Include simplify, interiors, and convex_hull query parameters on each /grid endpoint. These parameters can be used to simplify polygon geometry when format=geojson or format=kml. See the Polygon Simplification notebook (link below) for usage details.

  • Document polygon simplification in a new notebook.

Breaking changes

  • Slightly change default values for polygon simplification.

  • Deprecate the level_type query parameter.

3 March 2023

Extend HRES availability.

Features

  • Extend the time domain of HRES-based models to include the four year period from 2018 - 2021.

Fixes

  • Fix issue in /trajectory/cocip, /trajectory/cocip-contrail and /trajectory/profile endpoints (the endpoints that compute CoCiP) in which an explicit "met_source": "HRES" field in the request body was ignored. Now, the met_source parameter is used in every trajectory endpoint (previously it was only used on /trajectory/issr, /trajectory/sac, and /trajectory/pcr).

  • Fix similar issue in which met_source was ignored in fleet computation.

24 February 2023

Support custom engine types.

Features

  • Support an explicit engine_uid field on /trajectory payloads. An example of this can be found in the Comparison notebook.

  • Rewrite the Fleet Computation documentation. In particular, this notebook now uses a hand curated fleet sample instead of constructing synthetic flights in the notebook.

  • Rewrite all 400 error messages for consistency. Now all response bodies have the following structure:

    {
  "detail": {
    "msg": "some error message"
  }
}

  • Create table detailing the default engine UID mapping.

  • Use the latest sphinx-book-theme release for building documentation. This includes the ability to toggle between light and dark mode and a new search bar.

Fixes

  • Use upper-case ERA5 and HRES fields on the /grid/availability response. This is consistent with the enum values defining the met_source query parameter on /grid endpoints.

  • Better describe /grid query parameter enum values in the Get Started documentation.

8 February 2023

Fixes

  • Make notebooks more consistent.

6 February 2023

Features

  • Create new /trajectory/profile endpoint to compute CoCiP over a vertical profile defined by a flight trajectory. This endpoint extends the /trajectory/cocip endpoint by including an additional 2D array of predictions parameterized by 18 flight levels (270 - 440) and the flight trajectory itself. See the example notebook for usage details.

27 January 2023

Fixes

25 January 2023

Support off-hour gridded CoCiP requests.

Breaking changes

  • When serving gridded CoCiP requests, no longer floor the requested time to the previous hour. Instead, linearly interpolate pre-computed data from the nearest two hours. This allows for a first-order approximation of CoCiP predictions at off-hour times.

Fixes

  • Fix issue in which stale HRES meteorology data was used in the backend instead of the most recent data.

  • Improve backend memory management for large flight and fleet /trajectory requests.

Features

  • Increase the upper bound on the number of “flight” waypoints from 1000 to 5000.

  • Increase the upper bound on the number of “fleet” waypoints to 300,000.

  • Support HTTP/2 in the API.

18 January 2023

Features

  • Increase maximum flight duration to 20 hours.

  • Increase maximum fleet duration to 24 hours.

Fixes

  • Enhance backend memory management. This should reduce the frequency of 500 errors caused by memory exhaustion.

17 January 2023

Serve gridded CoCiP forecasts.

Features

  • Serve new gridded CoCiP data via the /grid/cocip endpoint. - Support additional aircraft_types in the /grid/cocip endpoint. Supported aircraft types now include: A320, A20N, A321, A319, A21N, A333, A350, B737, B738, B789, B77W. - Support both ERA5 and HRES-derived gridded CoCiP data. HRES-derived predictions are available from 2022-12-12 through ~24 hours into the future. ERA5-derived predictions are available from early 2022 through ~5 days into the past. Use the /grid/availability endpoint (see below) to check for the exact availability of CoCiP predictions. The choice of "ERA5" or "HRES" is made by the user with the met_source query parameter. The default value is "ERA5".

  • All gridded data products (CoCiP, PCR, SAC, ISSR) have a finer horizontal resolution. In particular, netCDF files now have 0.25 degree spacing in both latitude and longitude. Polygonal representations are computed using this finer resolution.

  • All gridded data products include additional flight levels. Flight levels now range from 270 to 440 (inclusive) in increments of 10.

  • Include new availability endpoint for checking the availability of gridded products. This allows checking the availability of gridded data before making a GET request to a /grid endpoint.

Breaking changes

  • No longer return nan values in gridded CoCiP predictions.

  • Remove the azimuth parameter from the /grid/cocip endpoint. Predictions are now invariant to azimuth. Any azimuth value provided is ignored.

  • Metadata on gridded CoCiP netCDF files may have slightly changed.

  • Contrail age predictions [minutes] on gridded CoCiP netCDF files now has dtype uint16.

  • Metadata (ie, GeoJSON properties) on polygon responses may have slightly changed.

12 January 2023

Features

  • Support additional ICAO aircraft types in /trajectory endpoints.

Fixes

  • Don’t overwrite true_airspeed if the incoming trajectory already has a true_airspeed field.

3 January 2023

Enhance polygon computation in /grid endpoints.

Features

  • Faster polygon computation in /grid endpoints. The new algorithm is 2x to 3x faster compared with `v0.10.0`_.

Fixes

  • Fix a bug in which degenerate polygons were served as GeoJSON in the /grid/cocip endpoint. Polygons are now guaranteed to be valid. Use 2 decimal places of precision in the GeoJSON output instead of 3 decimal places.

30 December 2022

Support for running contrail models with HRES forecast data.

Features

  • Return flight_id with all responses from /trajectory endpoints. If the input flight_id is a scalar, the id will be returned as a scalar. If the input flight_id is a list, it will be returned as a list.

  • Enable ECMWF HRES Forecast data to be used with all /trajectory endpoints. The user can specify the meteorology data source in the input Trajectory using the met_source key. Only two values supported for this key: "ERA5" or "HRES". "HRES" data is only available after 2022-12-12, and is available 48 hours ahead of the current time.

  • Enable ECMWF HRES Forecast data to be used in some /grid endpoints. The /grid/sac, /grid/issr, and /grid/pcr endpoints now accept a met_source query parameter. This takes a default value of "ERA5".

  • Allow the /grid/cocip endpoint to accept format="json" as a possible response format.

6 December 2022

Features

Fixes

  • Fix an internal bug in /trajectory endpoints caused by empty trajectory payloads. Now, empty trajectories will return a 422 error.

  • Include python syntax highlighting in the API Docs.

2 December 2022

Features

  • Extend maximum flight trajectory duration from 8 hours to 16 hours.

29 November 2022

Features

25 November 2022

Fix /auth/generate_key bug and update emissions model.

Breaking changes

  • Use a default (aircraft_type, engine) pair when an engine_uid field is not provided in a trajectory body. (Specifying the engine type is currently undocumented. This will be made more explicit in a future update.)

Features

  • Integrate latest updates to the Teoh nvPM emissions model. In particular, the T4/T2 methodology now approximates nvPM emissions for staged combustors (double annular combustors and twin annular premixing swirler combustors). For such aircrafts, nvPM emissions index numbers are reduced.

Fixes

  • Fix bug in the /auth/generate_key endpoint in which newly generated keys were not persisting in the authentication database.

15 November 2022

Additional documentation for custom requests.

Features

10 November 2022

Fixes

  • Fix bug in the /trajectory/cocip-contrail endpoint encountered when a trajectory does not produce any persistent contrails under CoCiP.

1 November 2022

New /trajectory/cocip-contrail endpoint.

Features

  • Add new /trajectory/cocip-contrail POST endpoint for disseminating raw CoCiP contrail predictions.

  • Include new Contrail Evolution documentation.

  • Include vertical pressure levels at 125, 100, and 70 hPa in backend met data stores.

  • Include predictions at 125 hPa in /grid/sac, /grid/issr, and /grid/pcr endpoints.

28 October 2022

Features

  • Better scaling for many incoming API requests.

20 October 2022

Breaking changes

  • Relax the minimum number of flight waypoints from 10 to 5 in /trajectory endpoints.

18 October 2022

Fixes

  • Fix a bug appearing in the /trajectory/cocip endpoint under fleet mode calculation.

14 October 2022

Breaking changes

  • Reduce minimum flight duration from 30 minutes to 5 minutes in /trajectory endpoints.

7 October 2022

Features

  • Support fleet (multiple flights) computation across all /trajectory endpoints. Include a flight_id field corresponding to each flight in the request body input to enable fleet computation.

  • Include humidity scaling metadata (name, formula) on the trajectory and grid response data.

  • Include new Fleet Computation documentation.

Breaking changes

  • Include new ERA5 humidity scaling (“exponential boost with latitude correction”) methodology. This new humidity scaling is a refinement of the previous implementation with an additional latitude-correction term which accounts for variation in the tropopause height.

Fixes

  • Fill nan values with 0 in initially_persistent response data from the /trajectory/cocip endpoint. Previously, values at which the SAC was not satisfied resulted in missing values in the initially_persistent field. These are now zero.

15 September 2022

Features

  • Improve met data handling and caching. This provides a significant speedup to the /trajectory/cocip endpoint.

Breaking changes

  • Reduce CoCiP max contrail age parameter from 16 hours to 12 hours.

9 September 2022

Fixes

  • A 422 error is now issued when trajectory time data is not sorted. Previously an internal server error (500) was encountered.

7 September 2022

Improve runtime performance and update schema examples.

Features

  • Support backend meteorology access via a Zarr store for faster data loading.

Fixes

  • Update schema examples for compatibility with trajectory endpoints. The previous trajectory example encountered a 422 error when run through the API.

  • Ensure flights traversing the antimeridian remain in-bounds for met interpolation.

Breaking changes

  • Duplicate times in flight trajectory are no longer allowed.

  • Minimum time gap between consecutive waypoints is reduced from 10 minutes to 5 minutes.

  • Round response floating point data to a reasonable decimal.

25 August 2022

Improve polygon calculation

Features

  • Provide a faster algorithm for grid –> polygon conversion.

  • Include CoCiP GeoJSON example in the Get Started notebook.

19 August 2022

Documentation update

Features

Fixes

  • Missing gridded CoCiP values are filled with 0 when constructing polygons responses.

Breaking changes

  • Redirect home page to https://apidocs.contrails.org/.

  • Rename /auth endpoints /auth/validate and auth/generate to auth/validate_key and auth/generate_key, respectively. The old paths are marked as deprecated and will be removed.

10 August 2022

Authorization and analytics

Features

  • Adds API key authorization to all endpoints - /v0/auth/validate: Validate API key - /v0/auth/generate: Generate API key with User ID - /v0/auth/list_keys: List API keys for User ID

1 August 2022

First “public” prototype

Features

  • Split endpoints by url path into /v0/grid and /v0/trajectory. Grid endpoints are HTTP GET requests. Trajectory endpoints are HTTP POST requests.

  • The current API contains the 9 endpoints:

    • /v0/grid/issr

    • /v0/grid/sac

    • /v0/grid/pcr

    • /v0/grid/cocip

    • /v0/trajectory/issr

    • /v0/trajectory/sac

    • /v0/trajectory/pcr

    • /v0/trajectory/emissions

    • /v0/trajectory/cocip

  • Grid endpoints support four types of response formats:

    • JSON (application/json)

    • NetCDF (application/netcdf)

    • GeoJSON (application/json)

    • KML (application/xml)

  • Trajectory endpoints support accept a JSON request body and respond with a JSON response body.

  • Grid endpoints support the following query parameters:

    • time: The time of the response grid.

    • bbox: The spatial bounding box of the grid.

    • level_type: The vertical resolution of the grid.

    • format: The format of the response. (One of json, netcdf, geojson, or kml.)

    • engine_efficiency: The engine efficiency of the aircraft. Only used for SAC and PCR.

    • aircraft_type, azimuth, threshold: Additional parameters for CoCiP.

  • Trajectory endpoints take in parameters via the request body. In addition to a sequence of waypoints, parameters can be passed in as vector-like quantities (a value per waypoint) or as scalar-like quantities (a single value used for all waypoints).