## 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 `` with your actual token. ```http GET https://farmmaps.eu/api/v1/folders/my_roots HTTP/1.1 Host: farmmaps.eu Accept: application/json Authorization: Bearer ``` **Response** The response will be something similar to: ```http 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 `` with your actual token. ```http GET https://farmmaps.eu/api/v1/items/f25d8765a1cd407cb235961c73c268cf:USER_IN/children HTTP/1.1 Host: farmmaps.eu Accept: application/json Authorization: Bearer ``` **Response** The response will be something similar to: ```http 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 `dataDate` and a `dataEndDate` to indicate the the timeframe of the growing season. The `dataDate` needs to be before `dataEndDate` and cannot be on the same day. **Request** ```http POST /api/v1/items HTTP/1.1 Accept: application/json Authorization: Bearer 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 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.