Summarizing changes that will be include in future v1 release
A pre-release note: This document summarizes the anticipated release of Regrow’s APIs - Intervention v1. This version is not live yet. There will be an announcement when it is live and ready for use by clients.
This release will be for the Intervention Module in Measure API and Explore API.
The Measure API Intervention module and Explore API are closely integrated and will be versioned together going forward to ensure compatibility and an improved developer and product experience. For context on Regrow’s new versioning approach see https://help.regrow.ag/versioning-of-measure-api-and-explore-api.
This version includes:
New features
- Autogen logic improvements for tillage
- Improved quantification for returning fields
- Adding a 'climate matched' baseline
- Support for multipolygons
- New baseline autogeneration methods supported
- Slimmed down output payloads
Feature updates and deprecations
- Simplifying legacy scenario type use
- Removed uncertainty distribution
- Weather and soil source changes
- Fuel_consumption, application event, tile, grazing, optional_ghg_boundary, defaulting baselines all deprecated
Technical improvements
- Version compatible routing
- Measure Intervention versioning compatibility
- Routing changes
- Schema simplifications
- Unification of field names
Features added
Feature/ Change |
Description |
Impact |
Autogen logic for tillage |
The counter-factual auto-generation logic was updated to more accurately account for tillage. Previously tillage could potentially have been dropped if it overlapped with another auto generated event in the counter factual or intervention (Explore). Now this tillage will be accounted for and not dropped. |
Only for fields that had a tillage event, which was replayed forward and then that event overlapped with another event (like a cropping event) the tillage event was dropped. The impact was causing these fields to look like a no tillage or reduced tillage field. |
Improved estimate quantification |
(For Explore API) for returning fields in a multi-year program, Explore was not accounting for continuation of a practice change, from a previous reporting period, but no new practice change (or different change) in current reporting period. Now we allow a client to declare an optional intervention period where a practice change occurred historically. See Explore v1 Integration Guide for implementation information. |
Estimates will be more aligned to final quantification numbers and reflective of real events on returning fields. |
Climate matched baseline |
A new baseline method is available with full product description defined here: https://help.regrow.ag/baseline-method-descriptions Can be utilized by setting baseline_method to climate_matched on project creation. |
This baseline method is not approved by protocol at the moment and should only be used for clients under the advice of Regrow for specific project types. |
Support for multi polygons |
Previously we only allowed “multi polygons” which were single fields with holes. This was challenging and caused clients to have to send a single lat/long point, which reduces field accuracy. Now we support multi polygons where a field is composed of multiple disconnected shapes. |
The API will no longer accept lat/long points, and will require a field boundary exclusively. |
Feature updates and deprecated
Feature/ Change |
Description |
Impact |
Simplifying legacy scenario type use (updated) |
Previously clients defining their own counterfactual required defining many duplicate events. We have simplified the schema for this now. |
Users have the option to define their counterfactual via See Scenario explainer for more information. |
Removed uncertainty distribution (deprecation) |
Previously the API would return the full uncertainty distribution with all outcomes. This caused the payloads to be extremely large and unused by clients. Now the array of uncertainty distributions will be removed from the standard payload. |
Uncertainty distribution will not be included as standard API output. If needed, contact your CS representative directly. |
Fuel_consumption (deprecation) |
Optional fuel calculation deprecated. This has long been soft deprecated, but we are now removing backwards compatibility |
These calculations are no longer supported. Minimal impact due to no active client use. |
Application events (deprecation) |
Application events deprecated. The transition period has ended. |
All clients should be transitioned to newer OrganicAmendmentEvent and FertilizerEvent types instead. |
Weather (scenario level deprecation) |
We are deprecating scenario level support for users to provide their own daily weather data due to lack of use of this feature. |
Regrow will provide this for all projects. |
weather_sources and soil_sources (deprecation) |
We previously allowed users to toggle between US and Global datasets at will. To align with our validation methodology we will now do this by default for all users. Ex. we will prioritize US datasets if the field location is in the US. |
Regrow will provide this for all projects. |
Tile and Grazing (deprecation) |
TileDrainageEvent and GrazingEvents are no longer supported |
Event types are not available. |
optional_ghg_boundary (deprecation) |
Currently specified at the ExploreInput level or the Measure Intervention project creation phase this feature optionally allows users to define their GHG boundary at a broader scope than purely on field. |
Minimal impact due to no active client use. |
Deprecation of default baseline methodology (deprecation) |
Previously there were default baselines applied if none were provided. |
All projects by have a baseline methodology declared by client. |
Tech Improvements
See developer docs for more details: API Docs: https://docs.dev.regrow.ag/measure/v1
- Version compatible routing
- All existing endpoints now require versioning prefexing to use the subsequent version:
- Example: requests to
/explore_api/fields
should now be made to/v1/explore_api/fields
- Example: requests to
- Going forward this should allow customers to opt into specific API versions by simply changing their route prefixes
- All existing endpoints now require versioning prefexing to use the subsequent version:
- Measure Intervention routing changes: All Measure - Intervention Module API routes will now be changed to be prefixed with /intervention (this is additive to the version compatible routing change)
- This is motivated by aligning with our new standard of module specific routing that has already been established for /inventory and /enteric
- The full list of the new routes is
"/intervention/projects/{project_name}"
"/intervention/projects/{project_name}/fields/{field_request_id}"
"/intervention/projects"
"/intervention/projects/{project_name}/finalize"
"/intervention/projects/{project_name}/fields"
"/intervention/protocols"
- Collapsing the
/project_level_scope_1
and/project_level_scope_3
endpoints into a single/intervention/projects/<project_name>
- Schema simplifications: Move location and soil objects from scenario level to top level InterventionInput class
-
- Historically these were defined twice at the scenario level (once for each scenario). This is redundant and preexisting validations already required these be the same for each scenario. This change makes it clear that these inputs apply to both scenarios and reduces the likelihood of user input error
-
- Unification of names: V1 Explore Input "
session_name
" changed to "name
" and V1 Intervention Input "session_name
" changed to "name
" which allows us to get closer alignment between products so clients can use similar language. - “
/v1/intervention/projects/{project_name}/fields
” JSON response changed to {“id”: int, “name”: string, “message”: string}