This document will describe the steps needed to use the Enteric module of the Measure API for a technical audience.
To use the Enteric module a 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, as well as calculated for individual ranchers.
Definitions
This is an abbreviated list of definitions for a technical audience. For more detailed definitions the Enteric Introduction article.
- Project: a collection of ranchers
- Rancher: it is an owner of one or more cattle cohorts; it has an associated practice change and a reporting period, for which the results will be calculated
- Cohort: contains information of a homogeneous cattle cohort through some period of time; it contains information such as livestock type, initial head count, diet parameters and management events that happened through the defined period of time
Steps
Overall, the usage goes as follows:
- The user creates a project
- The user submits one or more ranchers to the project
- The user can update and delete ranchers while the project is not finalized
- The user finalizes the project, which means all the ranchers 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 /enteric/projects:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/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.
Then a successful response confirms the creation:
{"message": "Created project my_project"}
Submit ranchers
We submit rancher information by making a POST request to endpoint /enteric/projects/{project_name}/ranchers. They must be uniquely named inside the project.
In this example we are going to submit two ranchers. The first one is called Rancher 1; it has two cohorts, one called Bulls Reproduction and another called Cows Reproduction. The reporting period for the cohorts is the year of 2023.
Cohort Bulls Reproduction is a non-terminal bulls cohort that starts on January 1st 2023 and ends on December 31st 2023. It started with 3 animals, has a total end weight of 1850 pounds and a starting diet of 36 pounds of dry matter per day. During 2023 one animal joined the cohort on May 16th and the diet changed on November 17th.
Cohort Cows Reproduction is a non-terminal cows cohort that starts on January 1st 2023 and ends on December 31st 2023. It started with 72 animals, has a total end weight of 1400 pounds and a starting diet of 32 pounds of dry matter per day. On May 2nd the diet changed.
The request to submit the ranger is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/projects/my_project/ranchers' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Rancher 1",
"practice_change": "soil_biology",
"cohorts": [
{
"start_date": "2023-01-01",
"end_date": "2023-12-31",
"name": "Bulls Reproduction",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
-71.00052534,
42.99947466
],
[
-71.00052534,
43.00052534
],
[
-70.99947466,
43.00052534
],
[
-70.99947466,
42.99947466
],
[
-71.00052534,
42.99947466
]
]
]
}
},
"livestock": {
"type": "beef_cattle",
"age_class": "bull"
},
"cohort_purpose_type": "non_terminal",
"initial_head_count": 3,
"total_end_weight": {
"value": 1850,
"unit": "pound"
},
"diet": {
"dry_matter_intake": {
"value": 36,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 49,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
},
"management_events": [
{
"date": "2023-05-16",
"type": "arrival",
"count": 1
},
{
"date": "2023-11-17",
"type": "diet_change",
"dry_matter_intake": {
"value": 36,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 59,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
}
]
},
{
"start_date": "2023-01-01",
"end_date": "2023-12-31",
"name": "Cows Reproduction",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
-71.00052534,
42.99947466
],
[
-71.00052534,
43.00052534
],
[
-70.99947466,
43.00052534
],
[
-70.99947466,
42.99947466
],
[
-71.00052534,
42.99947466
]
]
]
}
},
"livestock": {
"type": "beef_cattle",
"age_class": "cow"
},
"cohort_purpose_type": "non_terminal",
"initial_head_count": 72,
"total_end_weight": {
"value": 1400,
"unit": "pound"
},
"diet": {
"dry_matter_intake": {
"value": 32,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 49,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
},
"management_events": [
{
"date": "2023-05-02",
"type": "diet_change",
"dry_matter_intake": {
"value": 20,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 45.8,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
}
]
}
],
"reporting_information": {
"start_date": "2023-01-01",
"end_date": "2023-12-31"
}
}'
The response indicates the rancher was submitted. The most important property is the rancher_id, that must be used if we want to delete or update the rancher:
{
"data": {
"id": 418614,
"project_name": "my_project",
"rancher_name": "Rancher 1",
"rancher_id": 447283
},
"message": "Rancher uploaded"
}
Then we submit a second rancher called Rancher 2 also containing two cohorts. The reporting period for the cohorts is the year of 2013.
Cohort Weaned Heifers is a terminal weaned heifers cohort that starts on January 1st 2023 and ends on December 31st 2023. It started with 31 animals, has a total end weight of 650 pounds and a starting diet of 18 pounds of dry matter per day. During 2023 no events happened.
Cohort Weaned Steers is a terminal weaned steers cohort that starts on January 1st 2023 and ends on December 31st 2023. It started with 37 animals, has a total end weight of 700 pounds and a starting diet of 18 pounds of dry matter per day. During 2023 no events happened.
The request is the following:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/projects/my_project/ranchers' \
-H 'accept: application/json' \
-H 'x-apikey: <api_key>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Rancher 2",
"practice_change": "water_infrastructure",
"cohorts": [
{
"start_date": "2023-01-01",
"end_date": "2023-12-31",
"name": "Weaned Heifers",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
-71.00052534,
42.99947466
],
[
-71.00052534,
43.00052534
],
[
-70.99947466,
43.00052534
],
[
-70.99947466,
42.99947466
],
[
-71.00052534,
42.99947466
]
]
]
}
},
"livestock": {
"type": "beef_cattle",
"age_class": "weaned_heifer"
},
"cohort_purpose_type": "terminal",
"initial_head_count": 31,
"total_end_weight": {
"value": 650,
"unit": "pound"
},
"diet": {
"dry_matter_intake": {
"value": 18,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 49,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
},
"management_events": []
},
{
"start_date": "2023-01-01",
"end_date": "2023-12-31",
"name": "Weaned Steers",
"location": {
"boundary": {
"type": "Polygon",
"coordinates": [
[
[
-71.00052534,
42.99947466
],
[
-71.00052534,
43.00052534
],
[
-70.99947466,
43.00052534
],
[
-70.99947466,
42.99947466
],
[
-71.00052534,
42.99947466
]
]
]
}
},
"livestock": {
"type": "beef_cattle",
"age_class": "weaned_steer"
},
"cohort_purpose_type": "terminal",
"initial_head_count": 37,
"total_end_weight": {
"value": 700,
"unit": "pound"
},
"diet": {
"dry_matter_intake": {
"value": 18,
"unit": "pound",
"time_period": "day"
},
"neutral_detergent_fiber_percentage": 49,
"crude_protein_percentage": 0,
"acid_detergent_fiber_percentage": 0
},
"management_events": []
}
],
"reporting_information": {
"start_date": "2023-01-01",
"end_date": "2023-12-31"
}
}'
Response:
{
"data": {
"id": 418615,
"project_name": "my_project",
"rancher_name": "Rancher 2",
"rancher_id": 447284
},
"message": "Rancher uploaded"
}
Finalize project
As these are all the ranchers we want in the project we finalize it, so the outputs can be produced. We do it by making a POST request to endpoint /enteric/projects/{project_name}/finalize:
curl -X 'POST' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/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 /enteric/projects/{project_name}:
curl -X 'GET' \
'https://api.regrow.ag/dndc-scenarios-service/v0/enteric/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:
{
"co2eq_total": 607.6926105965999,
"co2eq_per_animal_unit": 4.315998654805397,
"co2eq_per_terminal_unit": 8.936656038185292,
"co2eq_per_pound_of_terminal_unit": 0.013196365050957653,
"co2eq_per_animal_stage": {
"bull": 86.72461775414999,
"cow": 4.818034319674999,
"weaned_heifer": 8.41271418,
"weaned_steer": 7.0484902589189184
},
"ranchers": {
"Rancher 1": {
"co2eq_total": 346.89847101659996,
"co2eq_per_animal_unit": 3.2481130245,
"co2eq_per_terminal_unit": 0,
"co2eq_per_pound_of_terminal_unit": 0,
"co2eq_per_animal_stage": {
"bull": 86.72461775414999,
"cow": 4.818034319674999
},
"practice_change": "soil_biology"
},
"Rancher 2": {
"co2eq_total": 260.79413958,
"co2eq_per_animal_unit": 7.670415869999999,
"co2eq_per_terminal_unit": 3.8352079349999997,
"co2eq_per_pound_of_terminal_unit": 0.005663282075570032,
"co2eq_per_animal_stage": {
"weaned_heifer": 8.41271418,
"weaned_steer": 7.0484902589189184
},
"practice_change": "water_infrastructure"
}
}
}
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-enteric-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"
}