diff --git a/Create-b-cropfield.md b/Create-b-cropfield.md new file mode 100644 index 0000000..7a36d1d --- /dev/null +++ b/Create-b-cropfield.md @@ -0,0 +1,215 @@ +## 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. +