217 lines
7.3 KiB
Markdown
217 lines
7.3 KiB
Markdown
## 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 `<acces token>` 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 <access token>
|
|
```
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
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 `<acces token>` 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 <access token>
|
|
```
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
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
|
|
|
|
```
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
**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.
|
|
|