## 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 a folder under this element (optional) * 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. **Request** Replace `` with your actual token. ```http GET https://farmmaps.awacc.nl/api/v1/folders/my_drive? HTTP/1.1 Host: farmmaps.awacc.nl Accept: application/json Authorization: Bearer ``` **Response** The response will be something similar to: ```http HTTP/1.1 200 OK Server: nginx/1.14.0 (Ubuntu) Date: Tue, 21 Apr 2020 09:57:07 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 Vary: Accept-Encoding { "url":"/api/v1/folders/f25d8765a1cd407cb235961c73c268cf:USER_FILES", "code":"f25d8765a1cd407cb235961c73c268cf:USER_FILES", "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 } ``` So the `parentcode` we need is **"f25d8765a1cd407cb235961c73c268cf:USER_FILES"** You can also find the code of a folder by browsing the folders in your FarmMaps account through the web interface. The item code is the last part of the URL. ### Create folder Depending on how you want to organise things, you might choose to make a separate folder for the cropfield. A folder can be created by creating an item with itemType `FOLDER`. > **Note:** At the moment, subfolders can not be created directly under the root folder, create a folder through the web interface first. **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: 210 { "parentCode": "f25d8765a1cd407cb235961c73c268cf:USER_FILES", "itemType": "FOLDER", "name": "My_new_folder", "data": {}, "dataDate": "2020-04-24T09:59:18.893Z", "geometry": {}, "tags": [ "string" ] } ``` When the folder is created successfully we should recieve something like this: **Response** ```http { "parentCode": "string", "geometry": {}, "data": {}, "tags": [ "string" ], "url": "string", "code": "string", "name": "My_new_folder", "created": "2019-12-18T10:16:21.455Z", "updated": "2019-12-18T10:16:21.455Z", "dataDate": "2019-12-18T10:16:21.455Z", "itemType": "string", "sourceTask": "string", "size": 0, "state": 0, "thumbnail": true } ``` ### 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": "6601a06d812b40f9830c9fe4e63b1944", "itemType": "vnd.farmmaps.itemtype.cropfield", "name": "cropfield for VRA", "dataDate": "2019-1-18T10:16:21.455Z", "dataEndDate": "2019-12-18T10:16:21.455Z", "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** When the cropfield is created, it should be visible through the FarmMaps web interface (under "My Drive" in the respective parent folder). We should have the following response: ```http HTTP/1.1 201 Created Server: nginx/1.14.0 (Ubuntu) Date: Fri, 24 Apr 2020 08:56:45 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.