Release Notes#


14 November 2023


  • 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" : [
      "issr" : [
      "pcr" : [
      "sac" : [
  • 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.


  • 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.


  • 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


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


16 October 2023


  • 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


  • Internal improvements


20 September 2023



21 July 2023


  • 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


  • 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.


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


  • 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.


v0.15.7, v0.15.8, v0.15.9#

21 June 2023


  • 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.


  • 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


  • 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


  • 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


  • Update backend to pycontrails v0.41. This update enables more performant trajectory interpolation and faster polygon constructions.


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


11 April 2023


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


10 April 2023


  • 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.


  • 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


21 March 2023

Better support for polygon simplification.


  • 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.


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


  • 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.


  • 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.


  • 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


  • Make notebooks more consistent.


6 February 2023


  • 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



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.


  • 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.


  • 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


  • Increase maximum flight duration to 20 hours.

  • Increase maximum fleet duration to 24 hours.


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


17 January 2023

Serve gridded CoCiP forecasts.


  • 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


  • Support additional ICAO aircraft types in /trajectory endpoints.


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


3 January 2023

Enhance polygon computation in /grid endpoints.


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


  • 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.


  • 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



  • 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


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


29 November 2022



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.)


  • 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.


  • 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.



10 November 2022


  • 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.


  • 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


  • 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


  • 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


  • 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.


  • 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


  • 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


  • 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.


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


  • 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


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

  • Include CoCiP GeoJSON example in the Get Started notebook.


19 August 2022

Documentation update



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

Breaking changes#

  • Redirect home page to

  • 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


  • 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


  • 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).