Technical guide with examples
To use the Inventory module the client must be configured in Measure API to be allowed to do so. This module is project based, which means results will be generated at a project level.
Definitions
- Project: a collection of fields
- Field: a physical field used for farming, in which management practices take place
Steps
- The user creates a project
- The user submits one or more fields to the project
- The user can delete fields while the project is not finalized
- The user finalizes the project, which means all the fields were submitted and the quantification calculations can begin
- The user retrieves the final project outputs
The intervention module has a decent amount of business logic and it is strong encouraged to read the product documentation in the knowledge base (https://help.regrow.ag/measure-api#intervention-module).
Example scope 3 project with blended baseline method
Create a project
We create the project making a POST request to endpoint /api/projects:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/api/projects?project_name=my_project&protocol=general_scope_3&baseline_method=blended' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-d ''
And get a success response:
{"message": "Created project my_project"}
Submit fields
A project can have any number of fields, but it’s best practice group fields with some commonality into projects. For example, fields can be grouped into projects based on a region (such as a country or climate region), a crop type (such that all fields growing the same crop are in a single project), or a reporting time period (such as a crop year).
A field (also referred to as a session input) is a collection of field data (such as field boundaries), field conditions (such as soil data) and farm management events (such as crop, tillage, irrigation and nutrient management data).
We submit field information by making a POST request to endpoint /api/projects/{project_name}/fields. They must be uniquely named inside the project.
In this example we are going to submit two fields. The first one is called Field 1; buckwheat, dry bean and corn are being planted between 2020 and 2023 with organic amendments and fertilizers applications, and there are multiple tillage events. Between 2023 and 2024, in the intervention period, barley is being planted, there is no organic amendments application and less tillage events at a smaller depth. The reporting period is between October 6th 2023 and August 5th 2024, and barley is the reporting crop.
The request to submit the field is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/api/projects/my_project/fields' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"session_name": "Field 1",
"scenarios": [
{
"name": "historical_baseline",
"location": {
"latlon": {
"latitude": 49.723453251,
"longitude": 5.324452634
},
"area": 1.854,
"area_unit": "hectare"
},
"rotations": [
{
"phases": [
{
"start_date": "2020-10-05",
"end_date": "2021-07-25",
"management_events": {
"cropping": [
{
"start_date": "2020-10-05",
"end_date": "2021-07-25",
"name": "buckwheat"
}
]
}
},
{
"start_date": "2021-07-26",
"end_date": "2022-08-15",
"management_events": {
"till": [
{
"date": "2022-08-05",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2021-09-05",
"end_date": "2022-08-15",
"name": "dry_bean",
"reductions": [
{
"date": "2022-08-15",
"type": "grain_harvest"
}
]
}
],
"organic_amendment": [
{
"date": "2022-08-05",
"name": "manure_compost",
"amount": 10400,
"depth": 5,
"application_method": "inject",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
},
{
"start_date": "2022-08-16",
"end_date": "2023-10-05",
"management_events": {
"till": [
{
"date": "2022-08-25",
"soil_inverted": false,
"depth": 5
},
{
"date": "2022-09-05",
"soil_inverted": false,
"depth": 5
},
{
"date": "2023-05-15",
"soil_inverted": false,
"depth": 5
},
{
"date": "2023-05-15",
"soil_inverted": false,
"depth": 10
}
],
"cropping": [
{
"start_date": "2022-08-25",
"end_date": "2023-05-15",
"name": "basic_cover_crop"
},
{
"start_date": "2023-05-15",
"end_date": "2023-10-05",
"name": "corn",
"reductions": [
{
"date": "2023-10-05",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2023-06-15",
"name": "urea_ammonium_nitrate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
}
],
"organic_amendment": [
{
"date": "2022-09-05",
"name": "manure_beef_solid",
"amount": 3333,
"depth": 5,
"application_method": "inject",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
}
]
}
],
"weather_sources": [
"GLOBAL"
],
"soil_sources": [
"GLOBAL"
],
"scenario_type": "historical_baseline"
},
{
"name": "intervention",
"location": {
"latlon": {
"latitude": 50.715623251,
"longitude": 4.129992634
},
"area": 1.854,
"area_unit": "hectare"
},
"rotations": [
{
"phases": [
{
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"management_events": {
"till": [
{
"date": "2024-03-15",
"soil_inverted": false,
"depth": 4
},
{
"date": "2024-03-25",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2024-03-25",
"end_date": "2024-08-05",
"name": "barley",
"reductions": [
{
"date": "2024-08-05",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2024-03-25",
"name": "urea_ammonium_nitrate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
}
]
}
}
]
}
],
"weather_sources": [
"GLOBAL"
],
"soil_sources": [
"GLOBAL"
],
"scenario_type": "intervention"
}
],
"reporting_information": {
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"crop_name": "barley",
"crop_yield": 3
}
}'
The response indicates the field was submitted. The most important property is the field_request_id, that is the identification of the field in the API and must be used if we want to delete the field:
{
"data": {
"id": "2574356",
"project_name": "my_project",
"session_name": "Field 1",
"field_request_id": 11962966
},
"message": "Session uploaded"
}
The second field is called Field 2. Between 2020 and 2023 we have a crop rotation of cover crop → corn → oat → canola, multiple fertilizer applications, organic amendments applications and frequent tillage events (from shallow to moderate). Between 2023 and 2024, in the intervention period, we have cover crop and corn, a single fertilizer application, no organic amendments and two shallow tillage events. The reporting period is between July 16th 2023 and October 5th 2024 and the reporting crop is corn.
The request to submit the field is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/api/projects/my_project/fields' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"session_name": "Field 2",
"scenarios": [
{
"name": "historical_baseline",
"location": {
"latlon": {
"latitude": 49.783456889,
"longitude": 3.946730679
},
"area": 1.768,
"area_unit": "hectare"
},
"rotations": [
{
"phases": [
{
"start_date": "2020-07-16",
"end_date": "2021-10-05",
"management_events": {
"till": [
{
"date": "2020-08-05",
"soil_inverted": false,
"depth": 5
},
{
"date": "2020-08-25",
"soil_inverted": false,
"depth": 5
},
{
"date": "2020-09-05",
"soil_inverted": false,
"depth": 5
},
{
"date": "2021-05-15",
"soil_inverted": false,
"depth": 10
},
{
"date": "2021-05-15",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2020-08-25",
"end_date": "2021-05-15",
"name": "basic_cover_crop"
},
{
"start_date": "2021-05-15",
"end_date": "2021-10-05",
"name": "corn",
"reductions": [
{
"date": "2021-10-05",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2021-06-15",
"name": "urea_ammonium_nitrate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
}
],
"organic_amendment": [
{
"date": "2020-08-05",
"name": "manure_compost",
"amount": 10400,
"depth": 5,
"application_method": "inject",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2020-09-05",
"name": "manure_beef_solid",
"amount": 3333,
"depth": 5,
"application_method": "inject",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
},
{
"start_date": "2021-10-06",
"end_date": "2022-07-25",
"management_events": {
"till": [
{
"date": "2022-02-25",
"soil_inverted": false,
"depth": 5
},
{
"date": "2022-03-05",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2022-03-05",
"end_date": "2022-07-25",
"name": "oat",
"reductions": [
{
"date": "2022-07-25",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2022-03-25",
"name": "urea_ammonium_nitrate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
}
]
}
},
{
"start_date": "2022-07-26",
"end_date": "2023-07-15",
"management_events": {
"till": [
{
"date": "2022-09-15",
"soil_inverted": false,
"depth": 3
},
{
"date": "2022-09-15",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2022-09-15",
"end_date": "2023-07-15",
"name": "canola",
"reductions": [
{
"date": "2023-07-15",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2022-10-15",
"name": "urea_ammonium_nitrate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
},
{
"date": "2023-03-15",
"name": "urea_ammonium_nitrate",
"amount": 300,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter" }
],
"organic_amendment": [
{
"date": "2022-09-15",
"name": "manure_compost",
"amount": 5200,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
}
]
}
],
"weather_sources": [
"GLOBAL"
],
"soil_sources": [
"GLOBAL"
],
"scenario_type": "historical_baseline"
},
{
"name": "intervention",
"location": {
"latlon": {
"latitude": 50.699206889,
"longitude": 3.871442599
},
"area": 1.768,
"area_unit": "hectare"
},
"rotations": [
{
"phases": [
{
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"management_events": {
"till": [
{
"date": "2024-04-05",
"soil_inverted": false,
"depth": 3
},
{
"date": "2024-05-15",
"soil_inverted": false,
"depth": 5
}
],
"cropping": [
{
"start_date": "2023-08-25",
"end_date": "2024-04-05",
"name": "alternative_blend_cover_crop"
},
{
"start_date": "2024-05-15",
"end_date": "2024-10-05",
"name": "corn",
"reductions": [
{
"date": "2024-10-05",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2024-05-15",
"name": "urea_ammonium_nitrate",
"amount": 250,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "liter"
},
{
"date": "2024-05-15",
"name": "ammonium_sulfate",
"amount": 100,
"depth": 0,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
}
]
}
],
"weather_sources": [
"GLOBAL"
],
"soil_sources": [
"GLOBAL"
],
"scenario_type": "intervention"
}
],
"reporting_information": {
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"crop_name": "corn",
"crop_yield": 13.2
}
}'
And the response:
{
"data": {
"id": "2574357",
"project_name": "my_project",
"session_name": "Field 2",
"field_request_id": 11962967
},
"message": "Session uploaded"
}
Finalize project
As these are all the fields we want in the project we finalize it, so the outputs can be produced. We do it by making a POST request to endpoint /api/projects/{project_name}/finalize:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/api/projects/my_project/finalize' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-d ''
The response means the calculations began:
{"message": "Approved project: my_project"}
Retrieving results
The results will be generated and go through Regrow's QA process. They can be retrieved via a GET request to endpoint /api/project_level_scope_3, where we can select which credit share type we want to see:
curl -X 'GET' \
'https://api.regrow.ag/dndc-scenarios-service/v0/api/project_level_scope_3?project_name=my_project&signed_url=false&credit_share_type=credit_share_enrollment' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>'
If they are not released yet (because they are in QA still) you will get a response like this (with status code 202 ACCEPTED):
{"detail": "Project results for project_name = 'my_project' are being processed"}
Once the results are released you will be alerted and then can retrieve them.
Response with credit share type credit_share_enrollment (uncertainty values removed for visibility):
{
"crop_level": {
"barley": {
"reporting_information": {
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"crop_name": "barley",
"total_yield": 13.744001317361402
},
"credit": {
"number_of_fields": 1,
"number_of_acres": 4.5813337724538,
"reversible_credits": {
"uncertainty_distribution": [
-0.9339908693559166,
...
-3.6034164409889406
],
"mean": -1.7353725656704222,
"standard_deviation": 4.2747382666429345,
"reporting_percentile": 45,
"total_reversible_emissions_reductions": -2.399740534018116
},
"non_reversible_credits": {
"uncertainty_distribution": [
1.733869712699677,
...
0.8654565782057759
],
"mean": 1.4524507035332006,
"standard_deviation": 1.2947855756662816,
"reporting_percentile": 45,
"total_non_reversible_emissions_reductions": 1.2716367132036932
},
"total_reversible_credit": -0.17460275785820592,
"total_non_reversible_credit": 0.09252303487466663,
"total_credit": -0.08207972298353929
}
},
"corn": {
"reporting_information": {
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"crop_name": "corn",
"total_yield": 57.66846550594271
},
"credit": {
"number_of_fields": 1,
"number_of_acres": 4.3688231443896,
"reversible_credits": {
"uncertainty_distribution": [
3.482710448908743,
...
0.9371093644172732
],
"mean": 2.7185017978386,
"standard_deviation": 4.076449436582905,
"reporting_percentile": 45,
"total_reversible_emissions_reductions": 2.0849513296407998
},
"non_reversible_credits": {
"uncertainty_distribution": [
2.118916579091419,
...
1.2907858230044629
],
"mean": 1.850551526121446,
"standard_deviation": 1.2347254033322468,
"reporting_percentile": 45,
"total_non_reversible_emissions_reductions": 1.67812480826677
},
"total_reversible_credit": 0.03615409758780466,
"total_non_reversible_credit": 0.02909952247808362,
"total_credit": 0.06525362006588828
}
}
},
"field_level": {
"11962966": {
"reporting_information": {
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"crop_name": "barley",
"crop_yield": null
},
"outcomes": {
"credit_share": -1.1281038208144227,
"reversible_outcomes": {
"credit_share": -2.399740534018116,
"dsoc": {
"baseline": -4.310167317252558,
"practice_change": -2.2774825946799933,
"preliminary_credit": -2.032684722572565,
"mean": -1.7353725656704222,
"standard_deviation": 4.2747382666429345,
"uncertainty_distribution": [
-0.9339908693559166,
...
-3.6034164409889406
]
}
},
"non_reversible_outcomes": {
"credit_share": 1.2716367132036932,
"mean": 1.4524507035332006,
"standard_deviation": 1.2947855756662816,
"direct_n2o": {
"baseline": 1.6235308301428044,
"practice_change": 0.1414897699740889,
"preliminary_credit": 1.4820410601687155,
"mean": 1.5036029644768865,
"standard_deviation": 1.2947855756662816,
"uncertainty_distribution": [
1.7850219736433628,
...
0.9166088391494618
]
},
"indirect_n2o": {
"baseline": 0.05260354241831289,
"practice_change": 0.10375580336199874,
"credit": -0.05115226094368586
},
"soil_ch4": null,
"fossil_fuel_co2": {
"baseline": 0,
"practice_change": 0,
"credit": 0
}
}
},
"field_name": "Field 1"
},
"11962967": {
"reporting_information": {
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"crop_name": "corn",
"crop_yield": null
},
"outcomes": {
"credit_share": 3.7630761379075697,
"reversible_outcomes": {
"credit_share": 2.0849513296407998,
"dsoc": {
"baseline": -3.8590089161307795,
"practice_change": -6.293989735866365,
"preliminary_credit": 2.4349808197355856,
"mean": 2.7185017978386,
"standard_deviation": 4.076449436582905,
"uncertainty_distribution": [
3.482710448908743,
...
0.9371093644172732
]
}
},
"non_reversible_outcomes": {
"credit_share": 1.67812480826677,
"mean": 1.850551526121446,
"standard_deviation": 1.2347254033322468,
"direct_n2o": {
"baseline": 2.549373493304097,
"practice_change": 1.0871779702332418,
"preliminary_credit": 1.462195523070855,
"mean": 1.4827572527455293,
"standard_deviation": 1.2347254033322468,
"uncertainty_distribution": [
1.7511223057155025,
...
0.9229915496285462
]
},
"indirect_n2o": {
"baseline": 1.0410788163032787,
"practice_change": 0.6732845429273622,
"credit": 0.3677942733759165
},
"soil_ch4": null,
"fossil_fuel_co2": {
"baseline": 0,
"practice_change": 0,
"credit": 0
}
}
},
"field_name": "Field 2"
}
}
}
Response with credit share type credit_share_weighted (uncertainty values removed for visibility):
{
"crop_level": {
"barley": {
"reporting_information": {
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"crop_name": "barley",
"total_yield": 13.744001317361402
},
"credit": {
"number_of_fields": 1,
"number_of_acres": 4.5813337724538,
"reversible_credits": {
"uncertainty_distribution": [
-0.9339908693559166,
...
-3.6034164409889406
],
"mean": -1.7353725656704222,
"standard_deviation": 4.2747382666429345,
"reporting_percentile": 45,
"total_reversible_emissions_reductions": -2.399740534018116
},
"non_reversible_credits": {
"uncertainty_distribution": [
1.733869712699677,
...
0.8654565782057759
],
"mean": 1.4524507035332006,
"standard_deviation": 1.2947855756662816,
"reporting_percentile": 45,
"total_non_reversible_emissions_reductions": 1.2716367132036932
},
"total_reversible_credit": -0.17460275785820592,
"total_non_reversible_credit": 0.09252303487466663,
"total_credit": -0.08207972298353929
}
},
"corn": {
"reporting_information": {
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"crop_name": "corn",
"total_yield": 57.66846550594271
},
"credit": {
"number_of_fields": 1,
"number_of_acres": 4.3688231443896,
"reversible_credits": {
"uncertainty_distribution": [
3.482710448908743,
...
0.9371093644172732
],
"mean": 2.7185017978386,
"standard_deviation": 4.076449436582905,
"reporting_percentile": 45,
"total_reversible_emissions_reductions": 2.0849513296407998
},
"non_reversible_credits": {
"uncertainty_distribution": [
2.118916579091419,
...
1.2907858230044629
],
"mean": 1.850551526121446,
"standard_deviation": 1.2347254033322468,
"reporting_percentile": 45,
"total_non_reversible_emissions_reductions": 1.67812480826677
},
"total_reversible_credit": 0.03615409758780466,
"total_non_reversible_credit": 0.02909952247808362,
"total_credit": 0.06525362006588828
}
}
},
"field_level": {
"11962966": {
"reporting_information": {
"start_date": "2023-10-06",
"end_date": "2024-08-05",
"crop_name": "barley",
"crop_yield": null
},
"credit_share": -1.1281038208144227,
"field_name": "Field 1"
},
"11962967": {
"reporting_information": {
"start_date": "2023-07-16",
"end_date": "2024-10-05",
"crop_name": "corn",
"crop_yield": null
},
"credit_share": 3.7630761379075697,
"field_name": "Field 2"
}
}
}