Release Notes#

v0.18.1#

14 November 2023

Fixes#

  • Address several internal server errors causing 500 errors.

v0.18.0#

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.

v0.17.2#

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.

v0.17.1#

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.

v0.17.0#

12 October 2023

Breaking Changes#

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

v0.16.5#

5 October 2023

Fixes#

  • Internal improvements

v0.16.4#

20 September 2023

Features#

v0.16.3#

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.

v0.16.2#

12 July 2023

Fixes#

  • Fix bug occasionally causing internal server errors.

v0.16.1#

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.

v0.16.0#

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#

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

21 June 2023

Fixes#

  • Internal improvements

v0.15.6#

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.

v0.15.5#

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.

v0.15.4#

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.

v0.15.3#

28 April 2023

Features#

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

Fixes#

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

v0.15.2#

11 April 2023

Fixes#

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

v0.15.1#

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.

v0.15.0#

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.

v0.14.0#

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.

v0.13.1#

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.

v0.13.0#

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.

v0.12.1#

8 February 2023

Fixes#

  • Make notebooks more consistent.

v0.12.0#

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.

v0.11.3#

27 January 2023

Fixes#

v0.11.2#

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.

v0.11.1#

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.

v0.11.0#

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.

v0.10.2#

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.

v0.10.1#

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.

v0.10.0#

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.

v0.8.6#

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.

v0.8.5#

2 December 2022

Features#

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

v0.8.4#

29 November 2022

Features#

v0.8.3#

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.

v0.8.2#

15 November 2022

Additional documentation for custom requests.

Features#

v0.8.1#

10 November 2022

Fixes#

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

v0.8.0#

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.

v0.7.0#

28 October 2022

Features#

  • Better scaling for many incoming API requests.

v0.6.3#

20 October 2022

Breaking changes#

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

v0.6.2#

18 October 2022

Fixes#

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

v0.6.1#

14 October 2022

Breaking changes#

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

v0.6.0#

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.

v0.5.2#

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.

v0.5.1#

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.

v0.5.0#

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.

v0.4.1#

25 August 2022

Improve polygon calculation

Features#

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

  • Include CoCiP GeoJSON example in the Get Started notebook.

v0.4.0#

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.

v0.3.0#

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

v0.2.0#

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