Describes the steps needed to use the Inventory module of the Measure API for a technical audience.
To use the Inventory module the client must be configured, by Regrow, in Measure API to be allowed to do so. This module is project based, which means results will be generated at a project level.
There is also outcomes returned at the field level which is to be used for grower payment purposes only.
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 and re-submit 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
Create a project
We create the project making a POST request to endpoint /inventory/projects:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/inventory/projects?project_name=my_project' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-d ''
The project must be uniquely named between all existing projects. The query parameter calculate_gases_percentages can be set to true to indicate that field percentages per gas should be calculated in the response.
The successful response confirms the creation:
{"message": "Created project my_project"}
Submit fields
We submit field information by making a POST request to endpoint /inventory/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; it has a wheat-barley rotation before the reporting period that goes from August 6th, 2023 to August 5th, 2024. In the reporting period canola was planted (and this is the reporting crop). It contains 3 years of data before the start of the reporting period, as this is the minimum required.
The request to submit the field is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/inventory/projects/my_project/fields' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"field_name": "Field 1",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[-94.513242699929, 37.8693247743648],
[-94.5132862489073, 37.8686964103168],
[-94.5134989189763, 37.8686738161371],
[-94.5135534773689, 37.8685836616781],
[-94.5134949549415, 37.8684800661862],
[-94.5133004719983, 37.868472627348],
[-94.5133419369005, 37.8677168151157],
[-94.5133901721379, 37.8677233287144],
[-94.5163811558933, 37.867822703659],
[-94.5162991967601, 37.869425818791],
[-94.513242699929, 37.8693247743648]
]
]
},
"area": 4.72978008575312,
"area_unit": "hectare"
},
"soil": {
"ph": 7,
"clay_fraction": 0.25,
"bulk_density": 1.25,
"soc": 0.0325,
"topsoil_depth": 30
},
"cultivation_cycles": [
{
"start_date": "2020-07-15",
"end_date": "2021-08-05",
"management_events": {
"till": [
{
"date": "2020-09-10",
"soil_inverted": false,
"depth": 10
},
{
"date": "2020-09-15",
"soil_inverted": false,
"depth": 10
},
{
"date": "2020-09-20",
"soil_inverted": false,
"depth": 10
},
{
"date": "2020-09-25",
"soil_inverted": false,
"depth": 10
}
],
"cropping": [
{
"start_date": "2020-09-25",
"end_date": "2021-08-05",
"name": "wheat_winter",
"reductions": [
{
"date": "2021-08-05",
"type": "hay_75"
}
]
}
],
"fertilizer": [
{
"date": "2021-02-15",
"name": "ammonium_nitrate",
"amount": 265,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2021-03-15",
"name": "ammonium_nitrate",
"amount": 176,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2021-04-15",
"name": "ammonium_nitrate",
"amount": 133,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
},
{
"start_date": "2021-08-06",
"end_date": "2022-08-01",
"management_events": {
"till": [
{
"date": "2022-01-16",
"soil_inverted": true,
"depth": 25
},
{
"date": "2022-01-21",
"soil_inverted": false,
"depth": 10
},
{
"date": "2022-01-26",
"soil_inverted": false,
"depth": 10
},
{
"date": "2022-01-31",
"soil_inverted": false,
"depth": 10
},
{
"date": "2022-02-05",
"soil_inverted": false,
"depth": 10
}
],
"cropping": [
{
"start_date": "2022-03-15",
"end_date": "2022-08-01",
"name": "barley",
"reductions": [
{
"date": "2022-08-01",
"type": "hay_75"
}
]
}
],
"fertilizer": [
{
"date": "2022-03-15",
"name": "ammonium_nitrate",
"amount": 176,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2022-04-15",
"name": "ammonium_nitrate",
"amount": 128,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
},
{
"start_date": "2022-08-02",
"end_date": "2023-08-05",
"management_events": {
"till": [
{
"date": "2022-09-10",
"soil_inverted": true,
"depth": 25
},
{
"date": "2022-09-15",
"soil_inverted": false,
"depth": 10
},
{
"date": "2022-09-20",
"soil_inverted": false,
"depth": 10
},
{
"date": "2022-09-25",
"soil_inverted": false,
"depth": 10
}
],
"cropping": [
{
"start_date": "2022-09-25",
"end_date": "2023-08-05",
"name": "wheat_winter",
"reductions": [
{
"date": "2023-08-05",
"type": "hay_75"
}
]
}
],
"fertilizer": [
{
"date": "2023-02-15",
"name": "ammonium_nitrate",
"amount": 265,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2023-03-15",
"name": "ammonium_nitrate",
"amount": 176,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2023-04-15",
"name": "ammonium_nitrate",
"amount": 133,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
},
{
"start_date": "2023-08-06",
"end_date": "2024-08-05",
"management_events": {
"till": [
{
"date": "2023-08-15",
"soil_inverted": false,
"depth": 10
},
{
"date": "2023-08-20",
"soil_inverted": false,
"depth": 10
},
{
"date": "2023-08-25",
"soil_inverted": false,
"depth": 10
}
],
"cropping": [
{
"start_date": "2023-08-25",
"end_date": "2024-08-05",
"name": "canola",
"reductions": [
{
"date": "2024-08-05",
"type": "grain_harvest"
}
]
}
],
"fertilizer": [
{
"date": "2024-02-15",
"name": "ammonium_nitrate",
"amount": 294,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2024-03-15",
"name": "ammonium_nitrate",
"amount": 176,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
},
{
"date": "2024-04-15",
"name": "ammonium_nitrate",
"amount": 151,
"application_method": "broadcast",
"area_unit": "hectare",
"rate_unit": "kilogram"
}
]
}
}
],
"reporting_information": {
"start_date": "2023-08-06",
"end_date": "2024-08-05",
"crop_name": "canola",
"crop_yield": 66.57
}
}'
The response indicates the field was submitted. The most important property is the field_request_id, that must be used if we want to delete the field:
{
"data": {
"id": "422963",
"project_name": "my_project",
"session_name": "Field 1",
"field_request_id": 460634
},
"message": "Session uploaded"
}
Then we submit a second field called Field 2. It has a fallow period until 2024, when barley was planted. The reporting period goes from August 21st 2023 to August 20th 2024. It also contains 3 years of data (start_year is set for this purpose).
The request is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/inventory/projects/my_project/fields' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"field_name": "Field 2",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
-89.25759477692819,
41.298473135647775
],
[
-89.2576846084566,
41.298518051412
],
[
-89.257774439985,
41.2986078829404
],
[
-89.25781935574922,
41.29869771446883
],
[
-89.25786427151341,
41.29878754599726
],
[
-89.25790918727763,
41.29887737752567
],
[
-89.25795410304185,
41.29896720905405
],
[
-89.25799901880605,
41.29905704058247
],
[
-89.25804393457022,
41.299146872110896
],
[
-89.25808885033447,
41.299236703639295
],
[
-89.25813376609867,
41.299281619403516
],
[
-89.25822359762708,
41.29932653516772
],
[
-89.25831342915546,
41.299371450931915
],
[
-89.25835834491967,
41.299416366696114
],
[
-89.25840326068392,
41.299551113988734
],
[
-89.25876258679756,
41.29968586128134
],
[
-89.2591219129112,
41.29973077704554
],
[
-89.25930157596801,
41.29977569280977
],
[
-89.25948123902484,
41.30004518739501
],
[
-89.25961598631746,
41.300314681980254
],
[
-89.25975073361008,
41.30044942927286
],
[
-89.25957107055325,
41.30058417656546
],
[
-89.25939140749644,
41.300674008093885
],
[
-89.25844817644811,
41.30076383962229
],
[
-89.25750494539977,
41.30071892385808
],
[
-89.25665154587986,
41.300674008093885
],
[
-89.25579814635994,
41.30049434503707
],
[
-89.2554837360105,
41.300314681980254
],
[
-89.25516932566109,
41.29968586128134
],
[
-89.25521424142528,
41.29905704058247
],
[
-89.25525915718949,
41.29901212481826
],
[
-89.25530407295366,
41.29896720905405
],
[
-89.2553489887179,
41.29901212481827
],
[
-89.2562023882378,
41.29905704058247
],
[
-89.25705578775771,
41.29901212481826
],
[
-89.2571456192861,
41.29896720905406
],
[
-89.25723545081456,
41.29892229328987
],
[
-89.25728036657875,
41.29887737752565
],
[
-89.25732528234298,
41.2985629671762
],
[
-89.25737019810718,
41.298248556826785
],
[
-89.25741511387137,
41.298338388355205
],
[
-89.25750494539977,
41.29842821988359
],
[
-89.25759477692819,
41.298473135647775
]
]
]
},
"area": 5.927926808523118,
"area_unit": "hectare"
},
"soil": {
"topsoil_depth": 30,
"total_depth": 50
},
"start_year": 2020,
"cultivation_cycles": [
{
"start_date": "2020-04-21",
"end_date": "2021-02-20",
"management_events": {
"irrigation": [],
"till": [],
"graze": [],
"flood": [],
"cropping": [],
"application": [],
"fertilizer": [],
"organic_amendment": [],
"tile_drainage": [],
"fire": []
}
},
{
"start_date": "2021-02-21",
"end_date": "2021-12-20",
"management_events": {
"irrigation": [],
"till": [],
"graze": [],
"flood": [],
"cropping": [],
"application": [],
"fertilizer": [],
"organic_amendment": [],
"tile_drainage": [],
"fire": []
}
},
{
"start_date": "2021-12-21",
"end_date": "2022-10-20",
"management_events": {
"irrigation": [],
"till": [],
"graze": [],
"flood": [],
"cropping": [],
"application": [],
"fertilizer": [],
"organic_amendment": [],
"tile_drainage": [],
"fire": []
}
},
{
"start_date": "2022-10-21",
"end_date": "2023-08-20",
"management_events": {
"irrigation": [],
"till": [],
"graze": [],
"flood": [],
"cropping": [],
"application": [],
"fertilizer": [],
"organic_amendment": [],
"tile_drainage": [],
"fire": []
}
},
{
"start_date": "2023-08-21",
"end_date": "2024-08-20",
"management_events": {
"till": [
{
"date": "2024-05-07",
"soil_inverted": false,
"depth": 7.6,
"crop_terminator": false
}
],
"cropping": [
{
"start_date": "2024-05-10",
"end_date": "2024-08-20",
"name": "barley",
"reductions": [
{
"date": "2024-08-20",
"custom": {
"frac_grain_removed": 1,
"frac_grain_residue": 0,
"frac_leaf_removed": 0.5,
"frac_leaf_residue": 0.5,
"frac_stem_residue": 0.5,
"frac_stem_removed": 0.5,
"frac_root_removed": 0,
"frac_root_residue": 0
}
}
]
}
]
}
}
],
"reporting_information": {
"start_date": "2023-08-21",
"end_date": "2024-08-20",
"crop_name": "barley",
"crop_yield": 100
}
}'
Response:
{
"data": {
"id": "422964",
"project_name": "my_project",
"session_name": "Field 2",
"field_request_id": 460635
},
"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 /inventory/projects/{project_name}/finalize:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/inventory/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 /inventory/projects/{project_name}:
curl -X 'GET' \
'https://api.regrow.ag/dndc-scenarios-service/v0/inventory/projects/my_project?signed_url=false' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>'
If they are not released yet (because they are in QA still) we 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 we can retrieve them.
Response:
{
"crop_level": {
"canola": {
"crop_yield": 778.0396125975419,
"number_of_fields": 1,
"number_of_acres": 11.68754112359234,
"direct_n2o_emissions": 2.6948802935425498,
"indirect_n2o_emissions": 5.202220160818628,
"soil_ch4_emissions": 0,
"total_emissions": 7.897100454361178,
"total_emissions_per_bushel": 0.010149997926193158,
"soc": 16.14239188635613,
"soc_per_bushel": 0.020747519310056178,
"ghg_emissions_factor": 0.010149997926193158,
"soc_emissions_factor": 0.020747519310056178,
"net_emissions_factor": 0.030897517236249335
},
"barley": {
"crop_yield": 1464.8226153463445,
"number_of_fields": 1,
"number_of_acres": 14.648226153463446,
"direct_n2o_emissions": 1.244602624910292,
"indirect_n2o_emissions": 0.4216393224005984,
"soil_ch4_emissions": 0,
"total_emissions": 1.6662419473108905,
"total_emissions_per_bushel": 0.001137504247855241,
"soc": 8.605117155612856,
"soc_per_bushel": 0.005874511401899848,
"ghg_emissions_factor": 0.001137504247855241,
"soc_emissions_factor": 0.005874511401899848,
"net_emissions_factor": 0.007012015649755089
}
},
"field_level": [
{
"field_name": "Field 1",
"crediting_crop": "canola",
"net_emissions_percentage": 100,
"area_acres": 11.6875,
"crop_yield_bushels_per_acre": 66.57
},
{
"field_name": "Field 2",
"crediting_crop": "barley",
"net_emissions_percentage": 100,
"area_acres": 14.6482,
"crop_yield_bushels_per_acre": 100
}
],
"field_level_value": [
{
"field_name": "Field 1",
"crediting_crop": "canola",
"net_emissions_factor": 0.03709775497582279,
"area_acres": 11.6875,
"crop_yield_bushels_per_acre": 66.57,
"indirect_n2o_emissions": 5.202220160818628,
"direct_n2o_emissions": 11.834752225955395,
"ch4_emissions": -0.2860846458222841,
"soc": 12.112533609953118,
"ghg_emissions_factor": 0.021529683591091673,
"soc_emissions_factor": 0.015568071384731116
},
{
"field_name": "Field 2",
"crediting_crop": "barley",
"net_emissions_factor": 0.002856987232954484,
"area_acres": 14.6482,
"crop_yield_bushels_per_acre": 100,
"indirect_n2o_emissions": 0.4216393224005984,
"direct_n2o_emissions": 0.2089165399160493,
"ch4_emissions": 0,
"soc": 3.554416176259739,
"ghg_emissions_factor": 0.0004304664479708413,
"soc_emissions_factor": 0.0024265207849836425
}
]
}
The query parameter signed_url makes the response be a URL that points to the project's results in the form of a JSON file, specially useful for big projects:
curl -X 'GET' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/projects/my_project?signed_url=true' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>'
Response:
{
"download_link": "https://storage.googleapis.com/rgrw-scenarios-service-inventory-dev/my_project/response.json?Expires=1747063658&GoogleAccessId=dndc-scenarios-service-sa%40flurosat-154904.iam.gserviceaccount.com&Signature=BB%2BS1aK26YjaLVnwuFGlL8PnWWeW%22F3SYhOhEwN9S02RomVvbp8IW7SvlLVWCl2ho%2F6TR9AVXTR5fJ%2B%2Fx8CMCtBT9jG1xm%2BXBZbXakjrs8TEgWYmoO3C0o2sA3thHCvHoArGHPm2jPQ%3D%3D"
}