Agriyieldz API Guide

Summary

This document describes how to access data available in the Agriyieldz data product hosted on the Eratos Senaps platform. For details about the methodology used to generate the data please refer to the Agriyieldz User Guide. This document will describe how to use the Senaps platform API to extract Agriyieldz data for a given location.

Prerequisites:

Authorisation and license agreement. You can purchase a subscription through our AgData Shop.
Some programming experience to consume REST API data services.

Data Structure and Variables

The Agriyieldz data is organised as a time series (also referred to as a data stream) per unique simulation output geo-located at each SILO Patch Point Data (PPD) weather station. There will typically be multiple simulations outputs for each weather station location to account for different soil types that occur in nearby paddocks. Simulations for over 1.9 million paddocks are available. Each paddock is linked to a corresponding simulation output and many paddocks may link to the same simulation output where the estimated soil type and nearest weather station match. Each simulation output is an array of the 12 output variables shown in Table 1. The time series for each paddock provides a simulation output for each of the 31 years simulated. The timestamp (date) for each simulation output represents the simulated harvest date for the crop that year. Note that on occasions, the conditions in the simulation fail to grow a successful crop, so for some paddocks data can be missing for some years.

Table 1. Simulation Output Indexes

Array Index	Simulation output variable	Unit of Measure

Array Index	Simulation output variable	Unit of Measure
0	Wheat grain weight	g/m²
1	Wheat above ground weight	g/m²
2	Plant available water at sow	mm
3	Plant available water at harvest	mm
4	In crop rain	mm
5	Plant available water capacity	mm
6	Mild frost count	days
7	Moderate frost count	days
8	Severe frost count	days
9	Mild heat count	days
10	Moderate heat count	days
11	Severe heat count	days

Accessing Agriyieldz data via API

Authentication

All AgData Shop API products are authenticated using the process described in Authentication for AgDataShop product APIs. After this process you will have obtained an Access Token which must be applied to every API request as a HTTP Authorization Bearer token. Please note tokens expire as per standard OAuth2 Client Credentials flow.

Authorization: Bearer <INSERT TOKEN>

Download process

The following examples query locations within the sample data product. You can signup to access it for free via the AgData Shop.

Accessing the Agriyieldz simulation output data is a two step process.

Find the nearest paddock to the location you're interested in, and then extract the relevant simulation stream ID.
Using the the simulation stream ID, download the simulation output data for the 31 years.

Step 1. Discovering the closest paddock and simulation stream ID for a given Location

Given a point longitude and latitude we can query the API to discover the nearest simulated location. Perform a HTTP GET request:

https://senaps.eratos.com/api/sensor/v2/locations?groupids=agriyieldz.v1&near=POINT( 142.8 -36.2)&radius=50000&limit=1&expand=true

In the API query above the near parameter is provided in Well-Known-Text format (https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) as a POINT object. For example the location at -36.2 degrees latitude and 141.8 longitude would be represented as POINT( 142.8 -36.2 ). Note that the coordinates are separated by a space. The radius parameter specifies the search radius in metres. We use the limit parameter (of 1) to request only the nearest result. Setting expand to True is required so the metadata containing the simulation ID is included in the results.

If successful, the above API request will return a status of 200 with a JSON encoded body as below:

{
	"_links": {
		"self": {
			"href": "https://senaps.eratos.com/api/sensor/v2/locations?expand=true&groupids=agriyieldz.v1&limit=1&near=POINT(%20142.8%20-36.2)&radius=50000"
		},
		"next": [
			{
				"href": "https://senaps.eratos.com/api/sensor/v2/locations?expand=true&groupids=agriyieldz.v1&limit=1&near=POINT( 142.8 -36.2)&radius=50000&skip=1"
			}
		]
	},
	"count": 1,
	"_embedded": {
		"locations": [
			{
				"_links": {
					"self": {
						"href": "https://senaps.eratos.com/api/sensor/v2/locations/agriyieldz.v1.vic.paddock.853467"
					}
				},
				"description": "Agriyieldz ePaddock 853467",
				"geojson": {
					"type": "Point",
					"coordinates": [
						142.80140419999999,
						-36.2023941
					]
				},
				"id": "agriyieldz.v1.vic.paddock.853467",
				"usermetadata": {
					"simulation_stream_id": "agriyieldz.v1.vic.simulation.1821",
					"perimeter": 2248.13161962,
					"area": 204331.541219,
					"hectares": 20.4331541219
				},
				"_embedded": {
					"organisation": [
						{
							"_links": {
								"self": {
									"href": "https://senaps.eratos.com/api/sensor/v2/organisations/csiro"
								}
							},
							"id": "csiro"
						}
					],
					"groups": [
						{
							"_links": {
								"self": {
									"href": "https://senaps.eratos.com/api/sensor/v2/groups/agriyieldz.v1.vic"
								}
							},
							"id": "agriyieldz.v1.vic"
						}
					]
				}
			}
		]
	}
}

The above response provides the simulation stream IDs (at path _embedded.locations[0].usermetadata['simulation_stream_id'] ) of the simulation output associated with this paddock. In this example the simulation stream ID of the nearest output is 'agriyieldz.v1.vic.simulation.1821'.

Step 2. Download data simulation output for a given simulation stream ID.

Given the simulation stream ID from step 1 above we can download the simulation output results.

If successful the API request will return a status of 200 with a JSON encoded body as below (Click > Expand source to see details):

The JSON property results contains a list of objects, one for each year of simulation output. Each object contains a timestamp and an array of data relating to the simulation for that year. The 2020 output is shown below.

As noted the t property contains the harvest date of the simulation data for the given year.

Interpreting this result using Table 1, gives meaning to the variables in the array path v.v. For example:

Array Index	Simulation output variable	Unit of Measure	Example value (v1, year 2020, WA simulation id 2045)

Array Index	Simulation output variable	Unit of Measure	Example value (v1, year 2020, WA simulation id 2045)
0	Wheat grain weight	g/m²	460.7
1	Wheat above ground weight	g/m²	1229.3
2	Plant available water at sow	mm	228.2
3	Plant available water at harvest	mm	46.3
4	In crop rain	mm	173.9
5	Plant available water capacity	mm	332.9
6	Mild frost count	days	0
7	Moderate frost count	days	0
8	Severe frost count	days	0
9	Mild heat count	days	2
10	Moderate heat count	days	2
11	Severe heat count	days	1

A programmatic method for determining variable names is available by querying the GET stream {id} API. eg.

GET https://senaps.eratos.com/api/sensor/v2/streams/agriyieldz.v1.vic.simulation.1821

The variable names are available in an array at JSON path usermetadata.variables

Further details about the above API calls can at the Senaps online API documentation

Python code examples of accessing Agriyieldz data

The following example demonstrate how to use Python code to download Agriyieldz data using the method described above.

Prerequisites:

Python 3.6+ environment with the senaps_sensor (version > 2.15.0), requests_oauth2client and pandas packages installed
- These can be installed using pip with the following command:
Valid AgDataShop CLIENT_ID and CLIENT_SECRET credentials.

Please refer to inline comments for explanations of the code.

The script will download results into the file agriyieldz_example.csv

The csv file should contain the following results: