Documentatie/Create-a-cropfield.md

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 <acces token> with your actual token.

GET https://farmmaps.awacc.nl/api/v1/folders/my_drive? HTTP/1.1
Host: farmmaps.awacc.nl
Accept: application/json
Authorization: Bearer <access token>

Response
The response will be something similar to:

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

POST /api/v1/items HTTP/1.1
Accept: application/json
Authorization: Bearer <access token>
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

{
  "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 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": "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/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.