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
The first step is to create a project. A project is a grouping of fields that will be modeled together. Give your project a unique title that will help you remember and track the 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
The next step is to submit fields to the project. A project can have any number of fields, but it’s recommended to group fields with some commonality. For example, you may choose to add fields into the same project 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 contains a collection of data grouped into cultivation cycles. Field data include:
- Field location (field boundaries, lat/long)
- Field conditions (soil data, if available and weather)
- Management events that happened on the field per cultivation cycle (such as crop planting/harvest, tillage, irrigation and nutrient management).
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"
}