Documentatie/Create-b-cropfield.md

217 lines
7.3 KiB
Markdown
Raw Normal View History

## 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.
2021-08-27 19:23:50 +00:00
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.
```http
2021-08-27 19:23:50 +00:00
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
HTTP/1.1 200 OK
2021-08-27 19:23:50 +00:00
Date: Fri, 27 Aug 2021 19:00:55 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
2021-08-27 19:23:50 +00:00
Server: Kestrel
Cache-Control: no-store,no-cache
Pragma: no-cache
2021-08-27 19:23:50 +00:00
Content-Length: 835
{
2021-08-27 19:23:50 +00:00
"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
}
```
2021-08-27 19:23:50 +00:00
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.
2021-08-27 19:23:50 +00:00
So make another call to check if a cropping scheme exist.
2021-08-27 19:23:50 +00:00
**Request**
Replace `<acces token>` with your actual token.
```http
2021-08-27 19:23:50 +00:00
GET https://farmmaps.eu/api/v1/items/f25d8765a1cd407cb235961c73c268cf:USER_IN/children HTTP/1.1
Host: farmmaps.eu
Accept: application/json
Authorization: Bearer <access token>
```
2021-08-27 19:23:50 +00:00
**Response**
The response will be something similar to:
```http
2021-08-27 19:23:50 +00:00
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
{
2021-08-27 19:23:50 +00:00
"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
}
```
2021-08-27 19:23:50 +00:00
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 <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
{
2021-08-27 19:25:30 +00:00
"parentCode": "f3ee8e3ac55b43bc89757bcaedc89992",
"itemType": "vnd.farmmaps.itemtype.cropfield",
2021-08-27 19:23:50 +00:00
"name": "cropfield test",
2021-08-27 19:25:30 +00:00
"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)
2021-08-27 19:23:50 +00:00
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.