281 lines
9.4 KiB
Markdown
281 lines
9.4 KiB
Markdown
## VRAHaulmkilling API
|
|
[<< Home](README.md)
|
|
|
|
FarmMaps is an asynchronous architecture, the API flow keeps this in mind.
|
|
The API expects that all data is already processed and available provided, for example through the normal FarmMaps flow (frontend).
|
|
|
|
For the currently available public FarmMaps API you can take a look at swagger: http://farmmaps.awtest.nl/swagger/index.html
|
|
|
|
**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.
|
|
|
|
**Users can poll the task api to see if a task is completed**
|
|
**This can be achieved with the task execution id obtained from calling the 'ItemTask' API.**
|
|
[Poll task status](Polling-task-status.md)
|
|
|
|
**Users can query the API for child items of a cropfield to see what items it has.**
|
|
|
|
### API flow
|
|
* Authenticate User
|
|
* Optional steps
|
|
* *Create cropfield through FarmMaps API*
|
|
* Item 'vnd.farmmaps.itemtype.cropfield' must be created with its data as specified in the api.
|
|
* Task 'vnd.farmmaps.task.workflow' can be executed if needed to aggregate all needed data.
|
|
* 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.
|
|
* Querying predefined haulmkilling agents (to use as input for the task).
|
|
* Task 'vnd.farmmaps.task.vrahaulmkilling' 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)
|
|
|
|
### Steps
|
|
[Authentication](Authentication.md)
|
|
|
|
##### Optional
|
|
[Create Cropfield](Create-Cropfield.md)
|
|
[Upload Data](Upload-Data.md)
|
|
|
|
###### Transform shape to geotiff
|
|
The VRAHaulmkilling 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 a sibling of the shape item with the same parent
|
|
This new geotiff item should be used as input to the a task.
|
|
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/items/{code}/tasks
|
|
{
|
|
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
|
}
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "string",
|
|
"taskType": "vnd.farmmaps.task.shapetogeotiff"
|
|
}
|
|
```
|
|
|
|
Response 400 Tasktype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in item
|
|
Response 404 Item not found
|
|
|
|
###### Querying predefined haulmkilling agents.
|
|
A list of haulmkilling agents can be requested by getting the "vnd.farmmaps.package.vra.haulmkilling" item and reading it's data field 'agents' array content.
|
|
> Request
|
|
```javascript
|
|
GET /api/v1/items/?it=vnd.farmmaps.package.vra.haulmkilling
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "....",
|
|
// ....
|
|
"data":
|
|
{
|
|
"agents": [
|
|
{
|
|
"name": "spotlightplus",
|
|
"values": {
|
|
"ndvi": [
|
|
{
|
|
"max": 0.95,
|
|
"min": 0.3,
|
|
"fexp": 1.35,
|
|
"fmul": 0.3,
|
|
"option": "risk.standard"
|
|
},
|
|
{
|
|
"max": 0.9,
|
|
"min": 0.25,
|
|
"fexp": 1.39,
|
|
"fmul": 0.25,
|
|
"option": "risk.low"
|
|
},
|
|
{
|
|
"max": 1,
|
|
"min": 0.35,
|
|
"fexp": 1.3,
|
|
"fmul": 0.36,
|
|
"option": "risk.high"
|
|
}
|
|
],
|
|
"wdvi": [
|
|
{
|
|
"max": 0.95,
|
|
"min": 0.3,
|
|
"fexp": 2.97,
|
|
"fmul": 0.3,
|
|
"option": "risk.standard"
|
|
},
|
|
{
|
|
"max": 0.9,
|
|
"min": 0.25,
|
|
"fexp": 2.97,
|
|
"fmul": 0.25,
|
|
"option": "risk.low"
|
|
},
|
|
{
|
|
"max": 1,
|
|
"min": 0.35,
|
|
"fexp": 2.97,
|
|
"fmul": 0.36,
|
|
"option": "risk.high"
|
|
}
|
|
]
|
|
},
|
|
"supportedOptions": [
|
|
"risk.standard",
|
|
"risk.low",
|
|
"risk.high"
|
|
]
|
|
}
|
|
],
|
|
"validOptions": [
|
|
"risk.standard",
|
|
"risk.low",
|
|
"risk.high",
|
|
"weed",
|
|
"split.first",
|
|
"split.second"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Response 400 Itemtype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No READ permissions in item
|
|
Response 404 Items not found
|
|
|
|
The data structure contains the haulmkilling **agents** and the **valid options** available in farmmaps.
|
|
Each agent contains a list of supported options and a key value map of a list of constants.
|
|
The key is a supported inputtype (wdvi, ndvi) and the value is a list of constant objects like so:
|
|
```javascript
|
|
{
|
|
"name": "agentName",
|
|
"values": {
|
|
"ndvi": [
|
|
{
|
|
"max": 0.9,
|
|
"min": 0.25,
|
|
"fexp": 2.97,
|
|
"fmul": 0.25,
|
|
"option": "risk.low"
|
|
},
|
|
{
|
|
"max": 0.95,
|
|
"min": 0.3,
|
|
"fexp": 1.35,
|
|
"fmul": 0.3,
|
|
"option": "risk.standard"
|
|
}
|
|
],
|
|
"wdvi": [{...}]
|
|
}
|
|
}
|
|
```
|
|
Each constant value object has an **'option'** associated with it that should also be within the **'validOptions'** list of the data structure.
|
|
|
|
###### Creating an application map with the VRAHaulmkilling task
|
|
Execute the task with the item code of the cropfield as parameter inside {code}.
|
|
Use the code of the input item inside {itemCode}, this specifies an item to use as input.
|
|
|
|
The resulting application map will be created as a child item of the cropfield item (this item can be queried).
|
|
> Request
|
|
```javascript
|
|
POST /api/v1/items/{code}/tasks
|
|
{
|
|
"taskType": "vnd.farmmaps.task.vrahaulmkilling",
|
|
"attributes": {
|
|
"inputCode": "{itemCode}",
|
|
"inputType": "wdvi",
|
|
"agentName": "reglone",
|
|
"selectedOption": "risk.standard"
|
|
}
|
|
}
|
|
```
|
|
> Response 201
|
|
```javascript
|
|
{
|
|
"code": "string", // code of task operation, can be queried for status
|
|
"taskType": "vnd.farmmaps.task.vrahaulmkilling",
|
|
"attributes": {
|
|
"inputCode": "{itemCode}",
|
|
"inputType": "wdvi",
|
|
"agentName": "reglone",
|
|
"selectedOption": "risk.standard"
|
|
}
|
|
}
|
|
```
|
|
|
|
Response 400 Tasktype not found
|
|
Response 401 Not authenticated
|
|
Response 403 No WRITE permissions in item
|
|
Response 404 Item not found
|
|
|
|
**'inputCode'** needs to have a value that is gotten from the haulmkilling agent query.
|
|
**'agentName'** needs to have a value that is gotten from the haulmkilling agent query.
|
|
**'inputType'** needs to have a value that is gotten from the haulmkilling agent query.
|
|
**'selectedOption'** needs to have a value that is gotten from the haulmkilling agent query.
|
|
|
|
The given agent values(agentName, inputType and selectedOption) as specified above form a unique combination specifying correct agent data.
|
|
For example, the agent with **'agentName'** needs to have an entry of **'inputType'** with a constant object with the **"option"** key and value **'selectedOption'**.
|
|
```javascript
|
|
{
|
|
"name": "<agentName>",
|
|
"values": {
|
|
"<inputType>": [
|
|
{
|
|
"max": 0.9,
|
|
"min": 0.25,
|
|
"fexp": 2.97,
|
|
"fmul": 0.25,
|
|
"option": "<selectedOption>"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
##### Optional input parameters #####
|
|
There are some optional task attribute input parameters for greater flexibility.
|
|
|
|
* **inputLayerName**
|
|
Allows you to specify which layer to use for an input item.
|
|
* **minPercentile** value between 0.0 - 1.0
|
|
Allows you to specify the minimum percentile value to 'filter' lower bound input data
|
|
* **maxPercentile** value between 0.0 - 1.0
|
|
Allows you to specify the maximum percentile value to 'filter' upperbound bound input data
|
|
* **plantingDate** if relevant
|
|
Allows you to specify the date the crop is planted.
|
|
* **measurementDate** if relevant
|
|
allows you to specify the date when the measurements were taken.
|
|
|
|
Default input layer name for Haulmkilling is the agent inputType used (wdvi, ndvi).
|
|
Default percentile values for Haulmkilling are 0.05 and 0.90.
|
|
Default dates are 'inherited' from the cropfield item passed to the task.
|
|
|
|
```javascript
|
|
{
|
|
"inputLayerName": "customLayerName",
|
|
"plantingDate": "2020-02-01T00:00:00.000Z",
|
|
"measurementDate": "2020-06-01T00:00:00.000Z",
|
|
"minPercentile": "0.1",
|
|
"maxPercentile": "0.95"
|
|
}
|
|
```
|
|
|
|
##### Create taskmap
|
|
[Create Taskmap](Create-Taskmap.md)
|
|
|
|
##### Download the data
|
|
In case the data is available it can be downloaded with the items API.
|
|
> Request
|
|
```javascript
|
|
GET /api/v1/items/{itemcode}/download
|