Tutorial : Variable Rate Application using API
Introduction
This section will show you how to use the VRA service using the SpaceSense API in a simple way.
The tutorial will follow the classic integration process in the following order :
- Login
- Register Fields
- Generate VRA.
This Tutorial covers the basics of using Variable Rate Application, if you are looking for API documentation we suggest you a couple of pages you might be interested in
Note : The crop health service required for the VRA is not included in the VRA pricing. Every field on which VRA is applied had to be registered in a Crop Health subscription first.
Login
To access the API and start writing and reading data you need to login.
You recieved your credentials in your first Email in the form of:
Username: custom-username
Password: secure-password
This tutorial doesn't cover your favorite language let us know: support@spacesense.ai
#import requests
import requests
# Creating the load for the request.
# replace custom-username and secure-password by your SpaceSense username and password
pload = {'username':'custom-username','password':'secure-password'}
# send the request a a post to the API adress and adds the load to the request
r = requests.post('https://spacesense-api.ew.r.appspot.com/login', data = pload)
# get the response Json in a dictionary.
r_dictionary = r.json()
# this is your API token for this session. you need to store and it and keep it.
token = r_dictionary['token']
curl -d 'username=custom-username&password=secure-password' https://spacesense-api.ew.r.appspot.com/login
Upon successful login you will recieve a token from the API now stored in the token
variable.
This token is required to talk to the API.
For every request you'll send to the API (except Login) you will add your token like a GET
request parameter.
Example : https://api-address/endpoint?token=__myToken__
in this example the token is __myToken__
Registering new fields
The SpaceSense API lets you register new fields using a specific json format called GeoJson
This section covers how to send a geojson to the API in order to register new fields.
Geojson
Geojson is an open standard format designed for representing simple geographical features using GPS coordinates.
GeoJson let you draw all different kinds of shapes or landmarks.
For the sake of this API's use you will only use GeoJson Polygon feature to register new fields.
Need more informations about GeoJson ? checkout those websites :
Create a Json body for the request
To register a new field you will need a GeoJson representing a polygon you can use Geojson.io to generate new Geojson.
Like this :
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[3.431151509284973, 45.583409896815034],
[3.4310495853424072, 45.58235490155467],
[3.432530164718628, 45.58246002652684],
[3.432524800300598, 45.58345870394514],
[3.431151509284973, 45.583409896815034]
]
]
}
}
]
}
NOTE : The first part (type, features, properties, etc . . .) is part of the GeoJson format. Remove it and your field won't get processed.
Now that you know what a GeoJson looks like, let's register a new Field.
Register new fields
The Polygon is not the only information we need to give the API, you need to build a complete Json body for the request.
Create a json and add a Field name as a string, an array of labels you want for this field, a geojson.
let's start with NDVI and a custom label (Farmer-34) to show how you can organize your fields.
Checkout the API documentation for this endpoint for more informations
The final Json will look something like that :
{
"field_name": "farm_9",
"label": ["NDVI", "Farmer-34"],
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-4.391269683837891, 39.71808094723828],
[-4.388244152069092, 39.71149505915214],
[-4.3865275382995605, 39.7120727937937],
[-4.387707710266113, 39.717800358315465],
[-4.391269683837891, 39.71808094723828]
]
]
}
}
]
}
}
This json will be referenced as __myJsonBody__
in the rest of this tutorial
To register a new Field you will need __myJsonBody__
and your Identification token referred to as __myToken__
in those examples.
#import requests & json libraries
import requests
import json
# Sends a post request using your identification Token and the Json previously built
r = requests.post('https://spacesense-api.ew.r.appspot.com/fields/register?token=' + __myToken__, json = json.loads(__myJsonBody__))
curl -h "Content-Type: application/json" -d __myJsonBody__ https://spacesense-api.ew.r.appspot.com/fields/register?token=__myToken__
After registering a field, wait a few minutes until the SpaceSense system downloads and produces crop health indices for your field for a specific historical period (based on your subscription)
Generate Variable Rate Application
Now that you have your field registered, you can create VRA zones with or without using your custom data.
We have some constraints on what kind of custom data you can use.
The custom data should be in Shapefile format.
It should be no larger than 5 MB.
Here are some examples of Shapefiles
We represent the data we use to create zones as layers in our API.
Checkout the API documentation for this endpoint for more information.
Layers
Types of layers
Crop Health Layer: Use this layer to reference to the crop health index generated by Spacesense. (mandatory)
- It has the following parameters:
type : 'crop_health'
weight: integer
Depending on if you want to use single date or a date range.
Single date
date: Date in isoformat. (isoformat :
'YYYY-MM-DD'
)Date range
start_date: Date in isoformat. (isoformat :
'YYYY-MM-DD'
)end_date: Date in isoformat. (isoformat :
'YYYY-MM-DD'
)index: crop health index to use. (ndvi, nirv, lai, chi etc). Make sure you have access to the index.
- Representation Example :
{"type": "crop_health", "weight" : 3, "date":"2020-08-09", "index":"ndvi"}
- Representation Example :
Custom layer : Use this layer when you want to provide your own custom data in a Shapefile format (Tiff in the future).
- It has the following parameters:
type : 'custom'
weight: integer
filename: reference to the file name (In case of shapfile, reference the
.shp
file)attribute: Name of the field inside the file that contains the custom data.
- Representation Example :
{"type": "custom", "weight" : 3, "filename":"homogenous_layer_VRA_Sample_1.shp", "attribute": "test_value"}
- Representation Example :
Rules for layers
- It is mandatory to have at least one CROP HEALTH layer
- CUSTOM layers are optional and only support Shapefiles for now. (Tiff in the future)
You can use multiple layers by adding to them to array as shown below.
Example :
[{"type": "crop_health", "weight" : 3,"index": "ndvi", "date":"2021-07-30"}, {"type": "custom", "weight" : 300, "filename":"homogenous_layer_VRA_Sample_1.shp", "attribute":"test_value"}]
The layers are not the only information we need to give the API, you need to build a complete Json body for the request.
Create a json and add a Field name as a string, a destination CRS of the output you want (integer), number of zones you want in the output (integer), layers, and files (if you want to use custom layer).
Let's start with crop health layer that uses NDVI and a custom layer with files (named homogenous_layer_VRA_Sample_1.shp, homogenous_layer_VRA_Sample_1.dbf ...) to show how your request will look like.
import requests
url = "https://spacesense-test.ey.r.appspot.com/v1/variable-rate-zones"
payload={'field_name': 'VRA_Sample_1',
'n_zones': '3',
'dst_crs': '4326',
'layers': '[{"type": "crop_health", "weight" : 3,"index": "ndvi", "date":"2021-07-30"}, {"type": "custom", "weight" : 300, "filename":"homogenous_layer_VRA_Sample_1.shp", "attribute":"test_value"}]'}
files=[
('files',('homogenous_layer_VRA_Sample_1.shx',open('__path__/homogenous_layer_VRA_Sample_1.shx','rb'),'application/octet-stream')),
('files',('homogenous_layer_VRA_Sample_1.shp',open('__path__/homogenous_layer_VRA_Sample_1.shp','rb'),'application/octet-stream')),
('files',('homogenous_layer_VRA_Sample_1.dbf',open('__path__/homogenous_layer_VRA_Sample_1.dbf','rb'),'application/octet-stream')),
('files',('homogenous_layer_VRA_Sample_1.prj',open('__path__/homogenous_layer_VRA_Sample_1.prj','rb'),'application/octet-stream'))
]
headers = {
'Authorization': 'Bearer __myToken__'
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
curl --location --request POST 'https://spacesense-api.ew.r.appspot.com/v1/variable-rate-zones' \
--header 'Authorization: Bearer __myToken__' \
--form 'field_name="VRA_Sample_1"' \
--form 'n_zones="5"' \
--form 'dst_crs="4326"' \
--form 'files=@"__path__/homogenous_layer_VRA_Sample_1.shx"' \
--form 'files=@"__path__/homogenous_layer_VRA_Sample_1.shp"' \
--form 'files=@"__path__/homogenous_layer_VRA_Sample_1.dbf"' \
--form 'files=@"__path__/homogenous_layer_VRA_Sample_1.prj"' \
--form 'layers="[{\"type\": \"crop_health\", \"weight\" : 3, \"date\":\"2021-03-07\", \"index\":\"ndvi\"},{\"type\": \"custom\", \"weight\" : 3, \"filename\":\"homogenous_layer_VRA_Sample_1.shp\", \"attribute\": \"test_value\"}]"'
In the response you receive a geojson with zones as polygons, that can be viewed in geojson.io or can be used to create a prescription map with your dose inputs.
Example Response :
{
"crs": {
"properties": {
"name": "urn:ogc:def:crs:EPSG::32632"
},
"type": "name"
},
"features":
[{
"geometry": {
"coordinates": [
[
[516096.87713129696,5015844.765313804],
[516106.9443245859,5015815.265386641],
.....
]
],
"type": "Polygon"
},
"properties": {
"DOSE": 0.0,
"RASTER_VAL": 0.294,
"ZONE": 2
}
}]
}
Recap
We just learned how to login, add fields to your spacesense account, create variable rate zones based on the crop health indices generated by SpaceSense and adding your own custom data (For example, soil moisture, yield etc.).
You should now checkout some more API features in the Documentation