Release Notes¶
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: [HERE](https://github.com/contrailcirrus/contrail-forecast/blob/main/docs/specs/forecast-api.md#20241009)
16 Oct 2024¶
Improvements¶
Add notebook for Contrail Forecast API /v1
Revise existing notebook documentation to reflect /v0 and /v1 differences
10 Oct 2024
Breaking Changes¶
Update the /v1 Contrail Forecast API to serve netCDF and GeoJSON data
in accordance with the working draft [Contrail Forecast specificaiton](https://contrailcirrus.github.io/contrail-forecast/).
11 Jul 2024¶
Features¶
Updates the API from pycontrails v0.49.3 -> v0.52.1.
See the [pycontrails release notes](https://github.com/contrailcirrus/pycontrails/releases) for descriptions of expected behavioral changes between these versions.
28 May 2024¶
Features¶
Release of the
v1
API routes, including/v1/grids
andv1/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¶
Backend changes.
Upgrade backend to pycontrails v0.49.2.
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 tohttps://api.contrails.org/v0
when running the notebooks.
19 December 2023¶
Features¶
Backend changes.
Upgrade backend to pycontrails v0.49.1.
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 themet_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 themet_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 withaltitude_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 peruser_id
moving forward.
5 October 2023¶
Fixes¶
Internal improvements
20 September 2023¶
Features¶
Upgrade to the latest version of pycontrails.
21 July 2023¶
Features¶
Add a
saf_blend
parameter to theTrajectory
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 anaircraft_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¶
Update backend to pycontrails v0.44.
Include an explicit
load_factor
in the Trajectory schema with default value 0.7. Ifaircraft_mass
is not provided, this field is used in the backend aircraft performance model to compute fuel mass flow rate.Swap the previous humidity correction method with a new histogram-matching approach.
Use a new cubic spline interpolation method for interpolating specific humidity.
When possible, use the Poll-Schumann aircraft performance model for computing aircraft performance.
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. TheProfileResponse
object now only contains aprofile
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 settingmode=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¶
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.
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, thelevel_type
parameter will be removed in the future.Include
simplify
,interiors
, andconvex_hull
query parameters on each/grid
endpoint. These parameters can be used to simplify polygon geometry whenformat=geojson
orformat=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, themet_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
andHRES
fields on the/grid/availability
response. This is consistent with the enum values defining themet_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¶
Rerun and cleanup static documentation for breaking changes in `v0.11.0`_.
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 additionalaircraft_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 themet_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 atrue_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 inputflight_id
is a scalar, the id will be returned as a scalar. If the inputflight_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 themet_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 amet_source
query parameter. This takes a default value of"ERA5"
.Allow the
/grid/cocip
endpoint to acceptformat="json"
as a possible response format.
6 December 2022¶
Features¶
Include Interpreting CoCiP EF Predictions documentation. This resource helps guide of the choice of the
threshold
parameter in the/grid/cocip
endpoint with polygon responses.Reorganize API Docs landing page.
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¶
Include new trajectory-grid comparison notebook.
25 November 2022¶
Fix /auth/generate_key
bug and update emissions model.
Breaking changes¶
Use a default
(aircraft_type, engine)
pair when anengine_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¶
Include new request customization documentation.
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 aflight_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 theinitially_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¶
Add documentation, including notebook examples.
Redirect OpenAPI documentation to https://api.contrails.org/openapi.
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
andauth/generate
toauth/validate_key
andauth/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 ofjson
,netcdf
,geojson
, orkml
.)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).