7.3 KiB
Creating a cropfield
This page explains what a cropfield is, and how to create one through the API.
Agricultural datasets generally refer to a specif crop, at a specific location at a specific time. Therefore, we need to create a "Cropfield" item, to define this location and a timeframe our data relates to. A cropfield provides a convienient way to group all data for a crop grown on a specific plot during a season. Farmmaps also uses the cropfield to collect and prepare context data such as weather, satelite imagery etc.
To create a cropfield we:
- Get the parent folder to place the cropfield under
- Create the cropfield
Prerequisites
To create a cropfield we need:
- an acces token
- coordinates of the cropfield (what points define the plot contour)
- a startdate and an end date (what timeframe does this data aply to)
Get parent element
First, we'll get the parent code needed to place the cropfield in the hierarchy. Usually this is a cropping scheme. So when the code of the crop field is known, use this code as parent code to create the crop field and go to the next chapter.
Get cropping scheme
When the cropping scheme code is not known, we need to start from the top of the hierarchy, which is my_roots.
Request
Replace <acces token> with your actual token.
GET https://farmmaps.eu/api/v1/folders/my_roots HTTP/1.1
Host: farmmaps.eu
Accept: application/json
Authorization: Bearer <access token>
Response
The response will be something similar to:
HTTP/1.1 200 OK
Date: Fri, 27 Aug 2021 19:00:55 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Server: Kestrel
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 835
{
"url":"/api/v1/folders/f25d8765a1cd407cb235961c73c268cf:USER_IN",
"code":"f25d8765a1cd407cb235961c73c268cf:USER_IN",
"name":"My Drive",
"created":"2019-09-25T19:39:33.841835",
"updated":"2019-09-25T19:39:33.841835",
"itemType":"ROOT_FOLDER",
"size":0,
"state":0,
"thumbnail":false
}
In the list returned, search for item which ends with USER_IN, which is shown above. This item will be the parent of the cropping scheme.
So make another call to check if a cropping scheme exist.
Request
Replace <acces token> with your actual token.
GET https://farmmaps.eu/api/v1/items/f25d8765a1cd407cb235961c73c268cf:USER_IN/children HTTP/1.1
Host: farmmaps.eu
Accept: application/json
Authorization: Bearer <access token>
Response
The response will be something similar to:
HTTP/1.1 200 OK
Date: Fri, 27 Aug 2021 19:17:36 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Server: Kestrel
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Length: 1519
{
"parentCode": "f25d8765a1cd407cb235961c73c268cf:USER_IN",
"geometry": {
"type": "Point",
"coordinates": [
47.566119,
7.605974
]
},
"data": {},
"tags": [],
"isEditable": false,
"url": "/api/v1/items/f3ee8e3ac55b43bc89757bcaedc89992",
"code": "f3ee8e3ac55b43bc89757bcaedc89992",
"name": "test scheme",
"created": "2021-08-27T19:11:40.195449Z",
"updated": "2021-08-27T19:11:40.195449Z",
"dataDate": null,
"dataEndDate": null,
"itemType": "vnd.farmmaps.itemtype.croppingscheme",
"sourceTask": null,
"size": 0,
"state": 0,
"thumbnail": false
}
When the list is empty, you need to create a new cropping scheme, which is described in another thread.
The parentcode we need for creating a crop field is "f3ee8e3ac55b43bc89757bcaedc89992"
Create the cropfield
Now we can create the cropfield. We do so by setting "itemType": "vnd.farmmaps.itemtype.cropfield" and adding data to the geometry parameter.
Generally, a cropfield contour would be defined as a polygon, so we add "type":"Polygon" and all the coordinates. We also need to specify a dataDateand adataEndDateto indicate the the timeframe of the growing season. ThedataDateneeds to be beforedataEndDate` and cannot be on the same day.
Request
POST /api/v1/items HTTP/1.1
Accept: application/json
Authorization: Bearer <acces token>
Content-Type: application/json
Cache-Control: no-cache
Host: farmmaps.awacc.nl
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 916
{
"parentCode": "f3ee8e3ac55b43bc89757bcaedc89992",
"itemType": "vnd.farmmaps.itemtype.cropfield",
"name": "cropfield test",
"dataDate": "2021-01-01T00:00:0.0Z",
"dataEndDate": "2021-12-31T00:00:00.0Z",
"data": {},
"geometry": {"type":"Polygon","coordinates":[[[6.09942873984307,53.070025028087],[6.09992507404607,53.0705617890585],[6.10036959220086,53.0710679529031],[6.10065149010421,53.0714062774307],[6.10087493644271,53.0716712354474],[6.10091082982487,53.0716936039203],[6.10165087441291,53.0712041549161],[6.10204994718318,53.0709349338005],[6.10263143118855,53.0705789370018],[6.10311578125011,53.0702657538294],[6.10331686552072,53.0701314102389],[6.103326530575,53.070119463569],[6.10309137950343,53.0699829669055],[6.10184241586523,53.0692902201371],[6.10168497998891,53.0691984306747],[6.10092987659869,53.0694894453514],[6.09942873984307,53.070025028087]]]}
}
Response
HTTP/1.1 201 Created
Server: nginx/1.14.0 (Ubuntu)
Date: Fri, 27 Aug 2021 19:21:36 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Cache-Control: no-store,no-cache
Pragma: no-cache
Content-Encoding: br
Location: /api/v1/items/8ecbaa2d85d5484db7f16b281b7cd013
Vary: Accept-Encoding
{
"parentCode":"6601a06d812b40f9830c9fe4e63b1944",
"geometry": {
"type":"Polygon",
"coordinates":[[
[6.09942873984307,53.070025028087],
[6.09992507404607,53.0705617890585],
[6.10036959220086,53.0710679529031],
[6.10065149010421,53.0714062774307],
[6.10087493644271,53.0716712354474],
[6.10091082982487,53.0716936039203],
[6.10165087441291,53.0712041549161],
[6.10204994718318,53.0709349338005],
[6.10263143118855,53.0705789370018],
[6.10311578125011,53.0702657538294],
[6.10331686552072,53.0701314102389],
[6.103326530575,53.070119463569],
[6.10309137950343,53.0699829669055],
[6.10184241586523,53.0692902201371],
[6.10168497998891,53.0691984306747],
[6.10092987659869,53.0694894453514],
[6.09942873984307,53.070025028087]]
]},
"data":{},
"tags":[],
"isEditable":false,
"url":"/api/v1/items/8ecbaa2d85d5484db7f16b281b7cd013",
"code":"8ecbaa2d85d5484db7f16b281b7cd013",
"name":"cropfield for VRA",
"created":"2020-04-24T08:56:45.3727807Z",
"updated":"2020-04-24T08:56:45.3727807Z",
"dataDate":"2019-01-18T10:16:21.455Z",
"itemType":"vnd.farmmaps.itemtype.cropfield",
"size":0,
"state":0,
"thumbnail":false
}
Troubleshooting
| Status code | Description |
|---|---|
| 201 | Cropfield created successfully |
| 401 | Error: not authenticated |
| 403 | Error: No write permissions in parent item |
| 404 | Error: Parent item not found |
Now that the cropfield has been created, we can start the processing by running a task. This will collext all context data for the cropfield. We need the ItemCode of the cropfield to start the task so keep this at hand.