HabiTerre API (1.0.0)

Download OpenAPI specification:Download

Introduction

The HabiTerre API enables access to full net-GHG calculation including both baseline & historical calculations and scenario forecasting.

Authentication

HabiTerre API uses OAuth2 access tokens for authentication, which are required to access all the resource endpoints. Users can get access to data while protecting their account credentials. OAuth2 is also a safer and more secure way to provide users access to their data.

OAuth2

In order to obtain an OAuth2 access token, the user can fetch it via the authorization tool in their request client or via code. The client_id and client_secret needs to be provided in the authorization body After the token is issued, the user can use it to access any endpoints in the HabiTerre API. The token is valid for 60 minutes from the time it was generated.

Security Scheme Type: OAuth2

Flow type: clientCredentials

Token URL: https://api.habiterre.com/oauth2/token

Orders

GHG quantification order with historical information for each field.

Create a new order

Order Requirement types

Intervention Inventory

Requirements for Intervention Orders:

Crop, tillage, fertilizer, and manure data for the year of practice change.
Three prior years of historical crop, tillage, fertilizer, and manure data.
Fertilizers: 10-34-0, Anhydrous Ammonia, TS, Custom Blend (liquid), KTS, UAN-28, UAN-32 → must be applied in gal/ac
Fertilizers: Ammonium Nitrate, AMS, Custom Blend (solid), DAP, K Mag, MAP, MESZ 12-40, NPSZ 12-45, Potash, Urea, Potassium Sulfate, ESN (Slow Release), Super U (Slow Release) → must be applied in lbs/ac
Manure: Lagoon liquid and Slurry liquid → gal/ac, Semi-dry or dry → lbs/ac

Requirements for Inventory Orders:

Crop, tillage, fertilizer, and manure data for the project year.
Fertilizers: 10-34-0, Anhydrous Ammonia, TS, Custom Blend (liquid), KTS, UAN-28, UAN-32 → must be applied in gal/ac
Fertilizers: Ammonium Nitrate, AMS, Custom Blend (solid), DAP, K Mag, MAP, MESZ 12-40, NPSZ 12-45, Potash, Urea, Potassium Sulfate, ESN (Slow Release), Super U (Slow Release) → must be applied in lbs/ac
Manure: Lagoon liquid and Slurry liquid → gal/ac, Semi-dry or dry → lbs/ac

Authorizations:

OAuth2

Request Body schema: application/json

One of

project_id required	string <uuid> The project ID under which this order will be submitted.
name	string Order Name.
crs	string <crs> Default: "EPSG:4326" The Coordinate Reference System (CRS) for the field boundary geometries in this order.
required	Array of objects A list of field objects containing geometry and field historical information.

Responses

Request samples

Payload

Content type

application/json

Example

Intervention Order

{"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"name": "My new order",
"crs": "EPSG:4326",
"fields": [{"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789",
"year_of_practice_change": 2020,
"cps_code": "340",
"crop": [{"year": 2020,
"type": "Alfafa",
"season": "Summer",
"yield": {"unit": "bu/ac",
"value": 216
},
"planting_date": "2020-06-15",
"planting_density": {"unit": "seeds/ac",
"value": 30
},
"termination_date": "2020-10-28",
"termination_method": "Mechanical harvest; grain",
"irrigation": true,
"residual_removal_method_after_termination": "Grazing",
"residual_removal_percentage_after_termination": "<25%"
}
],
"tillage": [{"date": "2020-11-05",
"type": "Deep tillage (deeper than 10 in)"
}
],
"fertilizer": [{"date": "2020-04-01",
"method": "Banded",
"types": [{"type": "UAN-28",
"rate": {"unit": "gal/ac",
"value": 20
},
"n_rate": {"unit": "lbs/ac",
"value": 30
},
"p_rate": {"unit": "lbs/ac",
"value": 15
},
"k_rate": {"unit": "lbs/ac",
"value": 10
}
}
],
"inhibitor": true
}
],
"manure": [{"date": "2020-07-01",
"form": "Lagoon liquid",
"animal_species": "Dairy cow",
"rate": {"unit": "gal/ac",
"value": 18525
},
"c_rate": {"unit": "lbs/ac",
"value": 3705
},
"n_rate": {"unit": "lbs/ac",
"value": 195
},
"p_rate": {"unit": "lbs/ac",
"value": 80
}
}
],
"soil_samples": [{"date": "2020-07-01",
"depth": "0-15cm",
"geometry": "POINT(-90.0851 40.53223)",
"soc": {"unit": "g C kg-1",
"value": 14.01
},
"bulk_density": {"unit": "Mg m-3",
"value": 0.21
}
}
]
}
]
}

Response samples

Content type

application/json

Example

Intervention Order

{"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"project_type": "Intervention",
"name": "My new order",
"crs": "EPSG:4326",
"fields": [{"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789"
}
]
}

Get Order by ID

Get the details of a submitted order.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

The UUID of the order

Responses

Response samples

Content type

application/json

Example

Intervention Order

{"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"project_type": "Intervention",
"name": "My new order",
"crs": "EPSG:4326",
"fields": [{"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789"
}
]
}

Update an order

Order Requirement types

Intervention Inventory

Requirements for Intervention Orders:

Crop, tillage, fertilizer, and manure data for the year of practice change.
Three prior years of historical crop, tillage, fertilizer, and manure data.
Fertilizers: 10-34-0, Anhydrous Ammonia, TS, Custom Blend (liquid), KTS, UAN-28, UAN-32 → must be applied in gal/ac
Fertilizers: Ammonium Nitrate, AMS, Custom Blend (solid), DAP, K Mag, MAP, MESZ 12-40, NPSZ 12-45, Potash, Urea, Potassium Sulfate, ESN (Slow Release), Super U (Slow Release) → must be applied in lbs/ac
Manure: Lagoon liquid and Slurry liquid → gal/ac, Semi-dry or dry → lbs/ac

Requirements for Inventory Orders:

Crop, tillage, fertilizer, and manure data for the project year.
Fertilizers: 10-34-0, Anhydrous Ammonia, TS, Custom Blend (liquid), KTS, UAN-28, UAN-32 → must be applied in gal/ac
Fertilizers: Ammonium Nitrate, AMS, Custom Blend (solid), DAP, K Mag, MAP, MESZ 12-40, NPSZ 12-45, Potash, Urea, Potassium Sulfate, ESN (Slow Release), Super U (Slow Release) → must be applied in lbs/ac
Manure: Lagoon liquid and Slurry liquid → gal/ac, Semi-dry or dry → lbs/ac

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

The UUID of the order

Request Body schema: application/json

One of

project_id required	string <uuid> The project ID under which this order will be submitted.
name	string Order Name.
crs	string <crs> Default: "EPSG:4326" The Coordinate Reference System (CRS) for the field boundary geometries in this order.
required	Array of objects A list of field objects containing geometry and field historical information.

Responses

Request samples

Payload

Content type

application/json

Example

Intervention Order

{"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"name": "My new order",
"crs": "EPSG:4326",
"fields": [{"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789",
"year_of_practice_change": 2020,
"cps_code": "340",
"crop": [{"year": 2020,
"type": "Alfafa",
"season": "Summer",
"yield": {"unit": "bu/ac",
"value": 216
},
"planting_date": "2020-06-15",
"planting_density": {"unit": "seeds/ac",
"value": 30
},
"termination_date": "2020-10-28",
"termination_method": "Mechanical harvest; grain",
"irrigation": true,
"residual_removal_method_after_termination": "Grazing",
"residual_removal_percentage_after_termination": "<25%"
}
],
"tillage": [{"date": "2020-11-05",
"type": "Deep tillage (deeper than 10 in)"
}
],
"fertilizer": [{"date": "2020-04-01",
"method": "Banded",
"types": [{"type": "UAN-28",
"rate": {"unit": "gal/ac",
"value": 20
},
"n_rate": {"unit": "lbs/ac",
"value": 30
},
"p_rate": {"unit": "lbs/ac",
"value": 15
},
"k_rate": {"unit": "lbs/ac",
"value": 10
}
}
],
"inhibitor": true
}
],
"manure": [{"date": "2020-07-01",
"form": "Lagoon liquid",
"animal_species": "Dairy cow",
"rate": {"unit": "gal/ac",
"value": 18525
},
"c_rate": {"unit": "lbs/ac",
"value": 3705
},
"n_rate": {"unit": "lbs/ac",
"value": 195
},
"p_rate": {"unit": "lbs/ac",
"value": 80
}
}
],
"soil_samples": [{"date": "2020-07-01",
"depth": "0-15cm",
"geometry": "POINT(-90.0851 40.53223)",
"soc": {"unit": "g C kg-1",
"value": 14.01
},
"bulk_density": {"unit": "Mg m-3",
"value": 0.21
}
}
]
}
]
}

Response samples

Content type

application/json

Example

Intervention Order

{"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"project_type": "Intervention",
"name": "My new order",
"crs": "EPSG:4326",
"fields": [{"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789"
}
]
}

Delete an order

Delete an order. An order can only be deleted when its status is still SUBMITTED.

Authorizations:

OAuth2

path Parameters

id

required

string <uuid>

The UUID of the order

Responses

Response samples

401
403
409
500

Content type

application/json

{"message": "The incoming token has expired"
}

Reports

When orders finish processing, reports for the fields will be available for downloading.

Get Ecosys report

Get crop history and carbon analysis for fields by order UUID and/or with user-given field ID(s).

Authorizations:

OAuth2

path Parameters

order_id

required

string <uuid>

UUID of the order

query Parameters

user_fid

Array of strings

A comma separated list of user-given field IDs belonging to an order

Responses

Request samples

cURL

curl --location 'https://api.habiterre.com/reports/ecosys/<order_id>?user_fid=<user_fid>' \
--header 'Authorization: Bearer <auth_token>'

Response samples

200
400
401
403
500

Content type

application/json

{"data": {"project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
"name": "My new order",
"crs": "EPSG:4326",
"status": "SUBMITTED",
"order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
"fields": [{"field_id": "e68e30b1-d177-4632-b748-463bcd0eedc6",
"user_fid": "123-456-789",
"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"ecosys_data": [{"year": 2018,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
},
{"year": 2019,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
},
{"year": 2020,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
},
{"year": 2021,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
},
"counterfactual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
},
{"year": 2022,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
},
"counterfactual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
},
{"year": 2023,
"factual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
},
"counterfactual": {"dsoc": 0,
"n2o_direct": 0,
"n2o_indirect": 0,
"ch4": 0,
"ghg": 0
}
}
],
"practice_data": [{"subfield_id": 0,
"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"crop": [{"year": 2020,
"type": "Alfafa",
"season": "Summer",
"yield": {"unit": "bu/ac",
"value": 216
},
"planting_date": "2020-06-15",
"planting_density": {"unit": "seeds/ac",
"value": 30
},
"termination_date": "2020-10-28",
"termination_method": "Mechanical harvest; grain",
"irrigation": true,
"residual_removal_method_after_termination": "Grazing",
"residual_removal_percentage_after_termination": "<25%"
}
],
"tillage": [{"date": "2020-11-05",
"type": "Deep tillage (deeper than 10 in)"
}
],
"fertilizer": [{"date": "2020-04-01",
"method": "Banded",
"types": [{"type": "UAN-28",
"rate": {"unit": "gal/ac",
"value": 20
},
"n_rate": {"unit": "lbs/ac",
"value": 30
},
"p_rate": {"unit": "lbs/ac",
"value": 15
},
"k_rate": {"unit": "lbs/ac",
"value": 10
}
}
],
"inhibitor": true
}
],
"manure": [{"date": "2020-07-01",
"form": "Lagoon liquid",
"animal_species": "Dairy cow",
"rate": {"unit": "gal/ac",
"value": 18525
},
"c_rate": {"unit": "lbs/ac",
"value": 3705
},
"n_rate": {"unit": "lbs/ac",
"value": 195
},
"p_rate": {"unit": "lbs/ac",
"value": 80
}
}
]
}
],
"metadata": {"component": "pipeline",
"version": {"input_processing_pipeline": "442fbb65e8a70bc7d6795f93436e0eb16928ba3e282a579b0ea27eb8376c1369",
"modeling_pipeline": "ec70f4e022a56dc9f4908cd59c4400cc622e399593e19a04e886ab99ce9d0127",
"ecosys_ht": "Ecosys_HT v1.0"
}
}
}
]
}
}

Get Comet-planner report

Get the carbon sequestration and greenhouse gas emission reduction estimates for an order and fields using order_id and/or user_fids during the cps year.

Authorizations:

OAuth2

path Parameters

order_id

required

string <uuid>

UUID of the order

query Parameters

user_fid

Array of strings

A comma separated list of user-given field IDs belonging to an order

Responses

Request samples

cURL

curl --location 'https://api.habiterre.com/reports/comet-planner/<order_id>?user_fid=<user_fid>' \
--header 'Authorization: Bearer <auth_token>'

Response samples

200
400
401
404
500

Content type

application/json

{"data": {"fields": [{"field_id": "e68e30b1-d177-4632-b748-463bcd0eedc6",
"comet_planner_data": {"2024": {"carbon_dioxide": 6.73,
"nitrogen": -1.81,
"methane": 0,
"total_co2_equivalent": 4.92
}
},
"geometry": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n",
"user_fid": "123-456-789"
}
],
"name": "My new order",
"crs": "EPSG:4326",
"status": "SUBMITTED",
"order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe"
},
"version": {"API": "v1.0.0"
}
}

Field Boundaries

HabiTerre provides proprietary farm field boundaries that can be searched by providing a GPS coordinate.

Get Field Boundaries

Get the geometry of a field boundary based on latitude and longitude.

Authorizations:

OAuth2

query Parameters

latitude required	string Latitude
longitude required	string Longitude

header Parameters

project_id

required

string <uuid>

Project ID associated with this request

Responses

Request samples

cURL

curl --location 'https://api.habiterre.com/field_boundaries?latitude=<latitude>&longitude=<longitude>' \
--header 'Authorization: Bearer <auth_token>' \
--header 'project_id: <project_id>' \

Response samples

Content type

application/json

{"data": {"field_boundaries": "POLYGON((-89.24726711599621 40.46755654139153,-89.25193022313758 40.46749158563945,-89.25198919321441 40.47102820419912,\n-89.24885929937489 40.471054844245025,-89.24739184746409 40.471071959939735,-89.24726711599621 40.46755654139153))\n"
},
"version": {"API": "v1.0.0"
}
}