Field Management
The Field API allows you to execute different queries for working with the field and get back a lot of information about your field that matches the query.
Youtube tutorial
Check out our video tutorial How to download vegetation trend with field_id?
Create Field
"Create Field" endpoint allow creating the field (your area of interest).
It’s based on HTTP requests sent to the server, the response format is JSON.
The area of interest is set via GeoJSON notation in the body of the request.
HTTP Request
POST 'https://api-connect.eos.com/field-management?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type": "Feature",
"properties": {
"name": "field name",
"group": "group name",
"years_data": [{
"crop_type": "name type of crop ",
"year": "year" ,
"sowing_date": "date"
}]
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat]
]
]
}
}'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| Request Body Parameter | Description |
|---|---|
| geometry | (required) A GeoJSON representation of a geometry describing the AOI. Supported geometry types: "Polygon". NOTE!: when you add coordinates in the first place - longitude and in the second - latitude. |
| properties.name | (optional) The name of field; |
| properties.group | (optional) The name of the field group to which this field belongs; |
| properties.years_data.crop_type | (optional) The name of crop type ; |
| properties.years_data.year | (optional) Year; |
| properties.years_data.sowing_date | (optional) Sowing date; |
HTTP Response
{
"id": number,
"area": number
}
Response parameters
| Parameter | Description |
|---|---|
| id | The field identifier; |
| area | The field area in hectare; |
Examples
Request
curl --location --request POST 'https://api-connect.eos.com/field-management' \
--data '{
"type": "Feature",
"properties": {
"name": "my field",
"group": "my group",
"years_data": [
{
"crop_type": "Wheat",
"year": 2023,
"sowing_date": "2023-04-01"
}
]
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-104.87931347024973, 27.166227117387663],
[-104.87190853064376,27.17371136921598],
[-104.87486446023671,27.175686643908065],
[-104.87271173924485,27.178599422270565],
[-104.87575466983847,27.180525385046096],
[-104.88103048496039,27.176643443128853],
[-104.87771956045358,27.172771682872458],
[-104.88236756436531,27.17042134807906],
[-104.87931347024973,27.166227117387663]
]
]
}
}'
Response
{
"id": 9793351,
"area": "77.0"
}
Update field
"Update field" endpoint allows changing the field name, group name and data about crop type and sowing period
HTTP Request
PATCH 'https://api-connect.eos.com/field-management/<field_id>?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"properties": {
"name": "field name",
"group": "group name",
"years_data": [{
"crop_type": "name type of crop ",
"year": "year" ,
"sowing_date": "date"
}]
}
}'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal; |
| field_id | (Required) The field identifier; |
| Request Body Parameter | Description |
|---|---|
| properties.name | (optional) The name of field; |
| properties.group | (optional) The name of the field group to which this field belongs; |
| properties.years_data.crop_type | (optional) The name of crop type; |
| properties.years_data.year | (optional) Year; |
| properties.years_data.sowing_date | (optional) Sowing date; |
HTTP Response
{
"monetization_included": <boolean>,
"id": number,
"geometry": {
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat]
]
],
"type": "Polygon"
},
"created": "creating data and time",
"properties": {
"years_data": [
{
"id": number,
"crop_type": "string",
"year": year,
"sowing_date": "date",
"aoi": field_id
}
],
"group": "string",
"name": "string",
"area": "number"
},
"updated": "updating data and time",
"type": "Feature"
}
Response parameters
| Parameter | Description |
|---|---|
| monetization_included | This parameter shows your field included or not in the paid tariff plan. default - false (not included); |
| id | The field identifier; |
| geometry | A GeoJSON representation of a geometry describing the field. |
| created | The date of creating the field; |
| updated | The date of updating the field; |
| properties.years_data.id | The identifier of crop period; |
| properties.years_data.crop_type | The name of crop type; |
| properties.years_data.year | Year; |
| properties.years_data.sowing_date | Sowing date; |
| properties.years_data.aoi | The field identifier; |
Examples
Request
curl --location --request PATCH 'https://api-connect.eos.com/field-management/9793351' \
--data '{
"properties": {
"years_data": [{
"crop_type": "Poppy seed",
"ndvi_list": "",
"year": 2023,
"sowing_date": "2023-01-14",
"fertilizer": "New fertilizer",
"aoi": 982
}],
"group": "New_group",
"name": "New_field"
},
"geometry": {
"coordinates": [
[
[-104.87931347024973, 27.166227117387663],
[-104.87190853064376,27.17371136921598],
[-104.87486446023671,27.175686643908065],
[-104.87271173924485,27.178599422270565],
[-104.87575466983847,27.180525385046096],
[-104.88103048496039,27.176643443128853],
[-104.87771956045358,27.172771682872458],
[-104.88236756436531,27.17042134807906],
[-104.87931347024973,27.166227117387663]
]
],
"type": "Polygon"
}
}'
Response
{
"id": 9793351,
"created": "2023-12-12T05:31:53.346153",
"updated": "2023-12-12T08:06:33.903377",
"monetization_included": true,
"properties": {
"years_data": [
{
"id": 11799559,
"crop_type": "Poppy seed",
"tillage_type": null,
"irrigation_type": null,
"target_yield": null,
"actual_yield": null,
"hybrid": null,
"fertilizer": "New fertilizer",
"aoi": 9793351,
"created_at": "2023-12-12T08:06:32.760089",
"updated_at": "2023-12-12T08:06:32.760133",
"year": 2023,
"sowing_date": "2023-01-14",
"harvesting_date": null,
"notes": null,
"maturity": null,
"field": 9793351,
"district": null,
"season": null
}
],
"group": "New_group",
"name": "New_field",
"area": "77.0"
},
"type": "Feature",
"geometry": {
"coordinates": [
[
[
-104.87931347024973,
27.166227117387663
],
[
-104.87190853064376,
27.17371136921598
],
[
-104.87486446023671,
27.175686643908065
],
[
-104.87271173924485,
27.178599422270565
],
[
-104.87575466983847,
27.180525385046096
],
[
-104.88103048496039,
27.176643443128853
],
[
-104.87771956045358,
27.172771682872458
],
[
-104.88236756436531,
27.17042134807906
],
[
-104.87931347024973,
27.166227117387663
]
]
],
"type": "Polygon"
}
}
Get field information
"Get field information" endpoint returns information about the field by field_id
HTTP Request
GET 'https://api-connect.eos.com/field-management/<field_id>?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| field_id | (Required) The field identifier; |
HTTP Response
{
"monetization_included": <boolean>,
"id": number,
"geometry": {
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat]
]
],
"type": "Polygon"
},
"created": "creating data and time",
"properties": {
"years_data": [
{
"id": number,
"crop_type": "string",
"year": year,
"sowing_date": "date",
"aoi": field_id
}
],
"group": "string",
"name": "string",
"area": "number"
},
"updated": "updating data and time",
"type": "Feature"
}
Response parameters
| Parameter | Description |
|---|---|
| monetization_included | This parameter shows your field included or not in the paid tariff plan. default - false (not included); |
| id | The field identifier; |
| geometry | A GeoJSON representation of a geometry describing the field. |
| created | The date of creating the field; |
| updated | The date of updating the field; |
| properties.years_data.id | The identifier of crop period; |
| properties.years_data.crop_type | The name of crop type; |
| properties.years_data.year | Year; |
| properties.years_data.sowing_date | Sowing date; |
| properties.years_data.aoi | The field identifier; |
Examples
Request
curl --location --request GET 'https://api-connect.eos.com/field-management/9793351'
Response
{
"id": 9793351,
"created": "2023-12-12T05:31:53.346153",
"updated": "2023-12-12T05:31:53.423296",
"monetization_included": true,
"properties": {
"years_data": [],
"group": "my group",
"name": "my field",
"area": "77.0"
},
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-104.87931347024973,
27.166227117387663
],
[
-104.87190853064376,
27.17371136921598
],
[
-104.87486446023671,
27.175686643908065
],
[
-104.87271173924485,
27.178599422270565
],
[
-104.87575466983847,
27.180525385046096
],
[
-104.88103048496039,
27.176643443128853
],
[
-104.87771956045358,
27.172771682872458
],
[
-104.88236756436531,
27.17042134807906
],
[
-104.87931347024973,
27.166227117387663
]
]
]
}
}
Get list of fields
"Get list of fields" endpoint returns the list of fields which available for the user.
HTTP Request
GET 'https://api-connect.eos.com/field-managements?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
HTTP Response
[{
"monetization_included": <boolean>,
"id": number,
"geometry": {
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat]
]
],
"type": "Polygon"
},
"created": "creating data and time",
"properties": {
"years_data": [
{
"id": number,
"crop_type": "string",
"year": year,
"sowing_date": "date",
"aoi": field_id
}
],
"group": "string",
"name": "string",
"area": "number"
},
"updated": "updating data and time",
"type": "Feature"
},
{............},
{
"monetization_included": <boolean>,
"id": number,
"geometry": {
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat]
]
],
"type": "Polygon"
},
"created": "creating data and time",
"properties": {
"years_data": [
{
"id": number,
"crop_type": "string",
"year": year,
"sowing_date": "date",
"aoi": field_id
}
],
"group": "string",
"name": "string",
"area": "number"
},
"updated": "updating data and time",
"type": "Feature"
}]
Response parameters
| Parameter | Description |
|---|---|
| monetization_included | This parameter shows your field included or not in the paid tariff plan. default - false (not included); |
| id | The field identifier; |
| geometry | A GeoJSON representation of a geometry describing the field. |
| created | The date of creating the field; |
| updated | The date of updating the field; |
| properties.years_data.id | The identifier of crop period; |
| properties.years_data.crop_type | The name of crop type; |
| properties.years_data.year | Year; |
| properties.years_data.sowing_date | Sowing date; |
| properties.years_data.aoi | The field identifier; |
Examples
Request
curl --location --request GET 'https://api-connect.eos.com/field-management/fields' \
--header 'x-api-key: <your_api_key>'
Response
[
{
"id": 9696734,
"created": "2023-10-12T10:06:55.356487",
"updated": "2023-10-12T10:06:55.457267",
"monetization_included": true,
"properties": {
"years_data": [],
"group": "002",
"name": "Agentina",
"area": "21.4"
},
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
-63.35755663231508,
-31.55514083182618
],
[
-63.35693921701535,
-31.555080357970397
],
[
-63.35333407940276,
-31.55511664228859
],
[
-63.354505039454395,
-31.55984557763498
],
[
-63.358912107283246,
-31.559766965579968
],
[
-63.35755663231508,
-31.55514083182618
]
]
]
}
},
...
{
"id": 9426835,
"created": "2023-07-12T11:08:11.089265",
"updated": "2023-07-12T11:08:11.128448",
"monetization_included": true,
"properties": {
"years_data": [],
"group": "002",
"name": "Trigo",
"area": "14.8"
},
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
26.563736749609745,
51.597960528691374
],
[
26.56425779219495,
51.59486037671212
],
[
26.56560110511265,
51.59495141192264
],
[
26.565894191568162,
51.594051166818986
],
[
26.569354239992464,
51.59435462221825
],
[
26.568613382564934,
51.598526928375804
],
[
26.563736749609745,
51.597960528691374
]
]
]
}
}
]
Delete Field
"Delete Field" endpoint allows deleting the field by field_id
HTTP Request
DELETE 'https://api-connect.eos.com/field-management/<field_id>?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| field_id | (Required) The field identifier; |
HTTP Response
response
code 204 /* it means the field has been deleted */
code 400 /* it means the field doesn't available for this user */
Examples
Request
curl --location --request DELETE 'https://api-connect.eos.com/field-management/9072755'
Response
code 204
Delete Fields
"Delete Fields" endpoint allows deleting all user fields
HTTP Request
DELETE 'https://api-connect.eos.com/field-managements?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
HTTP Response
response
code 204 /* it means all fields have been deleted */
Examples
Request
curl --location --request DELETE 'https://api-connect.eos.com/field-management/fields' \
--header 'x-api-key: <your_api_key>'
Response
code 204
Get crop type list
"Get crop type list" endpoint allows getting the list of available names for crop type.
HTTP Request
GET 'https://api-connect.eos.com/api/crop-types?api_key=<your_api_key>'
Request Parameters
| Request Path Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
Examples
Request
curl --location --request GET 'https://api-connect.eos.com/field-management/fields/crop-types'
Response
[
"Olive tree",
"Pasture",
"Poppy seed",
"Cherry",
"Summer fallow",
"Cassava",
"Ginger",
"Yams",
"Kola nut",
"Millet",
"Plantain",
"Bananas",
"Sesame",
"Milk thistle",
"Cashew",
"Gum arabic",
"Melon",
"Oil palm",
"Rubber",
"Turmeric",
"Wheat",
"Grapes",
"Vegetables",
"Beans",
"Nuts",
"Almonds",
"Potatoes",
"Rye",
"Rapeseed",
"Corn",
"Sugar Beet",
"Sunflower",
"Soybeans",
"Peas",
"Oats",
"Mixed cereals",
"Cotton",
"Flax",
"Rice",
"Pulses",
"Coffee",
"Cocoa",
"Tobacco",
"Tuber crops",
"Citrus",
"Sugarcane",
"Canola",
"Alfalfa",
"Fruit",
"Apple",
"Spice",
"Peanuts",
"Other",
"Spring Cereals",
"Spring Barley",
"Winter Rapeseed",
"Winter Barley",
"Spring Rapeseed",
"Winter Cereals",
"Sorghum",
"Winter Sorghum",
"Winter Wheat",
"Buckwheat",
"Oilseed Crops",
"Cereal"
]
Get field boundaries with classification by point (only for Ukraine)
**available only for Ukraine
For promotional use and to demonstrate the feature, this endpoint also works on the UA Demo field (check an example)
HTTP Request
To get geometry with the classification you need to create an HTTP request using the following pattern
GET https://api-connect.eos.com/api/cz/backend/api/field/<lat,lon>?api_key=<your_api_key>&year=<year1,year2>
Request Parameters
| Parameter | Default | Description |
|---|---|---|
api_key | none | (required) user’s API key |
<lat,lon> | none | (required) Point coordinate ( lat – latitude geographic coordinate that specifies the north-south position of a point on the Earth’s surface; lon – longitude is a geographic coordinate that specifies the east-west position of a point on the Earth’s surface.It is an angular measurement) |
year | none | optional Returns the crop classification and the field boundaries for the specified year. It is possible to set the list of comma separated years. If not specified in the responce you will receive crops classification for the all available years in your Plan and the field boundaries for the last available year |
HTTP Response
You will get the next response (if the point coordinates you specified is on the territory of Ukraine and years is available in your Product Plan)
{
"available": true,
"geometry": {
"type": "Polygon",
"coordinates": [
[
[lon,lat],
.........
[lon,lat]
]
]
},
"properties":
{
"year":"crop_type",
"year":"crop_type",
..................,
"year":"crop_type"
},
"area":"field_area",
"message": "Information is available for your Product Plan"
}
Response Parameters
| Parameter | Description |
|---|---|
available | logical value |
area | polygon area in hectares limited by coordinates specified in "geometry" |
message | information string |
properties | json array contains the year and his crop |
geometry | the GeoJSON representation of a geometry describing the AOI. Supported geometry types: “Polygon” |
If classification faeture is not available for your Product Plan and the coordinates of the specified point are not within the Demo field, you will get the next response.
{
"available": false,
"message": "Information isn't available for your Product Plan"
}
If the coordinates of the specified point do not contain the territory of Ukraine, you will get the next response.
{
"available": false,
"message": "No information available"
}
Example with Demo field
HTTP Request
curl --location --request GET 'https://api-connect.eos.com/api/cz/backend/api/field/49.593300,29.663600?api_key=<your api key>'
HTTP Response
{
"properties": {
"2019": "Soybeans",
"2018": "Maize",
"2017": "Soybeans",
"2016": "Maize"
},
"area": 40.45,
"geometry": {
"coordinates": [
[
[
29.659867,
49.596693
],
[
29.658108,
49.591491
],
[
29.667463,
49.590072
],
[
29.669137,
49.595135
],
[
29.659867,
49.596693
]
]
],
"type": "Polygon"
},
"available": true,
"message": "Information is available for your Product Plan"
}