Update page 'VRAHerbicide API'

This commit is contained in:
Mark van der Wal 2020-04-15 10:39:54 +00:00
parent 7577687972
commit 0dc2c6fe93

View File

@ -1,4 +1,4 @@
## VRANbs API v0.2
## VRAHerbicide API
[<< Home](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Home)
FarmMaps is an asynchronous architecture, the API flow keeps this in mind.
@ -6,11 +6,6 @@ The API expects that all data is already processed and available provided, for e
For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
**Limitations**
* Currently VRANbs only accepts input tiffs in WGS84/EPSG4326
* Data isn't automatically deleted as farmmaps has no support for this.
* But API users can delete their own items through the farmmaps API.
**Input preperation**
* Users can upload their own data if needed. (in case of when FarmMaps has not processed the required data).
* The farmmaps file API can be used for this.
@ -30,10 +25,7 @@ For the currently available public FarmMaps API you can take a look at swagger:
* This is an asynchronous process and can take a while before all data is collected in FarmMaps.
* *Upload own data*
* IF shape data, convert to geotiff.
* *Create 'vnd.farmmaps.itemtype.user.input' item for targetn calculation.*
* *Task 'vnd.farmmaps.task.vranbs' can be executed with the 'targetn' operation*
* *Task 'vnd.farmmaps.task.vranbs' can be executed with 'uptake' operation* to create an nitrogen uptake map.
* Task 'vnd.farmmaps.task.vranbs' must be executed with 'nitrogen' operation to create an appliance map.
* Task 'vnd.farmmaps.task.vraherbicide' must be executed to create an application map.
* Task 'vnd.farmmaps.task.taskmap' can be executed to create a taskmap.
* Download item data (tiff of shape)
@ -45,11 +37,11 @@ For the currently available public FarmMaps API you can take a look at swagger:
[Upload Data](https://git.akkerweb.nl/FarmMaps/Documentatie/wiki/Upload-Data)
###### Transform shape to geotiff
The VRANbs task only processes tiff items as input.
The VRAHerbicide task only processes tiff items as input.
If your input data is a processed shape file it first needs to be converted to geotiff, this can be done with the 'ShapeToGeoTiffTask'.
Pass the code of the shape item into the {code} parameter, this creates a new item with tiff data as the parent of the shape item.
This new geotiff item should be used as input to the vranbs task.
This new geotiff item should be used as input to the a task.
> Request
```javascript
@ -71,159 +63,36 @@ Response 401 Not authenticated
Response 403 No WRITE permissions in item
Response 404 Item not found
##### Using VRA Nitrogen fertilization task
The VraNbs task currently supports 3 operations:
* **targetn** - calculates the target nitrogen based on target yield.
* **uptake** - creates the nitrogen uptake map.
* **application** - creates the nitrogen fertilization application map.
###### Querying predefined herbicide agents.
###### targetn operation
Create a 'vnd.farmmaps.itemtype.user.input' item to use in this operation.
(step not needed if you already know the target nitrogen you want to work with.)
The user.input item must parent the '{user_code}:USER_IN' item and can be obtained by calling following request:
> Request
```javascript
GET /api/v1/Folders/my_uploads
```
> Response 201
```javascript
{
"url": "/api/v1/folders/{user_code}:USER_IN",
"code": "{user_code}:USER_IN",
"name": "Uploaded",
"created": "2020-03-04T14:41:41.099557",
"updated": "2020-03-04T14:41:41.099557",
"itemType": "FOLDER",
"size": 0,
"state": 0,
"thumbnail": false
}
```
**Create item**
Create user.input item, pass just obtained parent code as parameter in {user_code}.
> Request
```javascript
POST /api/v1/items
{
"parentCode": "{user_code}:USER_IN",
"itemType": "vnd.farmmaps.itemtype.user.input",
"name": "TargetN",
"dataDate": "2020-03-02T14:22:09.265Z"
}
```
> Response 201 Created
```javascript
{
"parentCode": "string",
"geometry": {},
"data": {},
"tags": [
"string"
],
"url": "string",
"code": "string",
"name": "string",
"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
}
```
Response 401 Not authenticated
Response 403 No WRITE permissions in parent item
Response 404 Parent Item not found
**Call the vranbs task**
Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}.
Use the code obtained from creating the user.input item as a parameter in {itemCode}.
> Request
```javascript
POST /api/v1/items/{code}/tasks
{
"taskType": "vnd.farmmaps.task.vranbs",
"attributes": {
"operation": "targetn",
"inputCode": "{itemCode}",
"plantingDate": "2020-02-01T00:00:00.000Z",
"measurementDate": "2020-06-01T00:00:00.000Z",
"purposeType": "consumption", // consumption, fries, potato, starch
"targetYield": "60"
}
}
```
> Response 201
```javascript
{
"code": "string",
"taskType": "vnd.farmmaps.task.workflow"
}
```
Response 400 Tasktype not found
Response 401 Not authenticated
Response 403 No WRITE permissions in item
Response 404 Item not found
**Query user.input targetN item**
You can query the user.input item to get the calculated targetN value from the data field of the item.
> Request
```javascript
GET /api/v1/items/{code}
```
> Response 200
```javascript
{
"parentCode": "string",
"geometry": {},
"data": {
"TSum": "2700",
"TargetYield": "60",
"TargetN": "249.2341"
},
"tags": [
"string"
],
"url": "string",
"code": "string",
"name": "TargetN",
"created": "2019-12-18T10:16:21.455Z",
"updated": "2019-12-18T10:16:21.455Z",
"dataDate": "2019-12-18T10:16:21.455Z",
"itemType": "vnd.farmmaps.itemtype.user.input",
"sourceTask": "string",
"size": 0,
"state": 0,
"thumbnail": true
}
```
###### Uptake map operation
Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}.
###### Creating an application map with the VRAHerbicide task
Execute the task with the item code of the cropfield as parameter inside {code}.
Use the input map code inside {itemCode}, specifying an inputCode for the input data item.
{itemCode} needs the code of the data input item passed into it. ex. uploaded isaria/data data.
The resulting nitrogen uptake map will be created as a child item under the cropfield item (this can be queried).
{itemCode} needs the code of the data input item passed into it.
An **optional** {extraItemCode} can be passed inside the 'extraInputcode' field to process herbicide from 2 inputs.
The resulting application map will be created as a child item of the cropfield item (this can be queried).
> Request
```javascript
POST /api/v1/items/{code}/tasks
{
"taskType": "vnd.farmmaps.task.vranbs",
"taskType": "vnd.farmmaps.task.vraherbicide",
"attributes": {
"operation": "uptake",
"inputCode": "{itemCode}",
"plantingDate": "2020-02-01T00:00:00.000Z",
"measurementDate": "2020-06-01T00:00:00.000Z",
"inputType": "irmi", // yara, ci, irmi or wdvi
"extraInputCode": "{extraItemCode}",
"agent": {
"SoilType": "Dalgrond",
"ExtraInputType": "Lutum",
"MinDosis": 2,
"MaxDosis": 3,
"A": 0.1428,
"B": 1.285714,
"C": 1,
"D": 97,
"E": 3,
"P": 1,
"Crop": "Zetmeelaardappelen"
}
}
}
```
@ -231,51 +100,23 @@ POST /api/v1/items/{code}/tasks
```javascript
{
"code": "string", // code of task operation, can be queried for status
"taskType": "vnd.farmmaps.task.vranbs",
"taskType": "vnd.farmmaps.task.vraherbicide",
"attributes": {
"operation": "uptake",
"inputCode": "{itemCode}",
"inputType": "irmi", // yara, ci, irmi or wdvi
}
}
```
Response 400 Tasktype not found
Response 401 Not authenticated
Response 403 No WRITE permissions in item
Response 404 Item not found
###### Application map operation
Execute the VRANbsTask with the item code of the cropfield as parameter inside {code}.
Use the input map code inside {itemCode}, specifying an inputCode for the input data item.
{itemCode} needs the code of the data input item passed into it. ex. uploaded isaria/data data.
The resulting nitrogen application map will be created as a child item under the cropfield item (this can be queried).
> Request
```javascript
POST /api/v1/items/{code}/tasks
{
"taskType": "vnd.farmmaps.task.vranbs",
"attributes": {
"operation": "application",
"inputCode": "{itemCode}",
"plantingDate": "2020-02-01T00:00:00.000Z",
"measurementDate": "2020-06-01T00:00:00.000Z",
"inputType": "irmi", // yara, ci, irmi or wdvi
"targetN": "249.22948"
}
}
```
> Response 201
```javascript
{
"code": "string", // code of task operation, can be queried for status
"taskType": "vnd.farmmaps.task.vranbs",
"attributes": {
"operation": "nitrogen",
"inputCode": "{itemCode}",
"inputType": "irmi", // yara, ci, irmi or wdvi
"targetN": "249.22948"
"extraInputCode": "{extraItemCode}",
"agent": {
"SoilType": "Dalgrond",
"ExtraInputType": "Lutum",
"MinDosis": 2,
"MaxDosis": 3,
"A": 0.1428,
"B": 1.285714,
"C": 1,
"D": 97,
"E": 3,
"P": 1,
"Crop": "Zetmeelaardappelen"
}
}
}
```