Documentation

Table of Contents

Getting Started

To access the API as a developer, you’ll need to have a Unique Client ID setup and be granted an API Key for each active Green Brain user that you are working with.

To start, contact us and we’ll send you 3 things.

  1. Your unique client identifier with an API Key for the publicly available Green Brain Demo.
  2. A Green Brain User Account that let’s you view the Green Brain Demo using our interactive front-end, to help you understand the data structure and presentation.
  3. An Integration Partner User Agreement to be signed and returned.

From this point, once the User Agreement has been signed and returned, you can begin to build an API integration with data coming through the Green Brain Demo. Beyond this, you’ll need to have each active Green Brain user confirm in writing (email is best) directly to service@greenbrain.ag that they approve the sharing of their data with you. They should include:

  • The Property Name in Green Brain from which their data can be shared;
  • The Organisation to which access to the data can be granted; and
  • The duration of access (if nothing is specified, a default duration of 1 year will be applied).

Once this written confirmation is received by Green Brain, you’ll be issued an additional API Key for the system/s that they own, which will enable you to extract their data for further use in line with the practices outlined in the User Agreement.

Basic Information

URL: https://api.greenbrain.ag

To access any of the API resources, you must first be authorized. This can be achieved using your client identifier and API Key to request a bearer token.

These header credentials are required to make subsequent requests.

Authorization: Bearer YOUR_TOKEN_HERE
X-Client-ID: YOUR_CLIENT_ID_HERE
X-API-Key: YOUR_API_KEY_HERE
Headers
Header Description
Authorization Your access token retrieve from the above “Authorization” section
e.g. Bearer YOUR_ACCESS_TOKEN
x-client-id Your unique client identifier
x-api-key Your API Key

Authorization

Request for an access token.

info
Tokens will expire after 30 days

[GET] /auth/token

Request:

https://api.greenbrain.ag/auth/token
Headers
Header Description
x-client-id Your unique client identifier
x-api-key Your purpose API Key
Response 
{
  "token": "xxxx.yyyyy.zzzzz",
  "expiry": 1680311692
}

Properties

[GET] /properties

Get a list of accessible properties and sites.

Request:

https://api.greenbrain.ag/properties
Parameters (none)
Response 
{
  "properties": [
    {
      "id": 19,
      "name": "Green Brain Demo",
      "sites": [
        {
          "id": 195,
          "name": "Hub"
        },
        {
          "id": 197,
          "name": "Soil Moisture Tension (kPa)"
        },
        {
          "id": 196,
          "name": "Soil Moisture Tension (kPa): Battery"
        },
        {
          "id": 199,
          "name": "Moisture Content (%)"
        },
        {
          "id": 198,
          "name": "Moisture Content (%): Battery"
        },
        {
          "id": 1485,
          "name": "Rainfall + Air Temp, Humidity & Leaf Wetness: Rainfall"
        },
        {
          "id": 2909,
          "name": "Rainfall + Air Temp, Humidity & Leaf Wetness: Temperature, Humidity & Leaf Wetness"
        },
        {
          "id": 1484,
          "name": "Rainfall + Air Temp, Humidity & Leaf Wetness: Battery"
        }
      ]
    }
  ]
}

Readings

Below contain API resources relating to sensor and weather readings.

[GET] /readings

Get minute readings for a site.

info
Each request enables you to retrieve minutely data for a 24-hour period or daily data spanning a month.

Request:

https://api.greenbrain.ag/readings?from=2023-01-17&to=2023-01-18&type=10,13&property=19&site=2909
Parameters
URL Description
property (Required) Target property
site (Required) Target site
type The sensor type to gather readings from
e.g.
type=10
type=4,6,10
(See below for a list of available sensor types)
from Starting date/time range
e.g. from=2022-01-01
(See below for supported date/time formats)
to Ending date/time range
e.g. to=2022-01-02
(See below for supported date/time formats)
Response 
{
  "labels": ["2023-01-17T00:00:00+10:30:00", "2023-01-17T00:30:00+10:30:00"],
  "datasets": [
    {
      "id": 16621,
      "name": "Minimum",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [25.952, 27.84],
      "valueType": 1
    },
    {
      "id": 16622,
      "name": "Average",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [27.834, 28.638],
      "valueType": 2
    },
    {
      "id": 16623,
      "name": "Maximum",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [28.612, 29.223]
    },
    {
      "id": 16630,
      "name": "Minimum",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [11.3, 11.04],
      "valueType": 1
    },
    {
      "id": 16631,
      "name": "Average",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [12.49, 12.26],
      "valueType": 2
    },
    {
      "id": 16632,
      "name": "Maximum",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [13.4, 13.37],
      "valueType": 3
    }
  ]
}

[GET] /readings/calculated

Get minutely calculated readings for a site.

Request:

https://api.greenbrain.ag/readings/calculated?from=2023-01-17&to=2023-01-18&type=23,24&property=19&site=2909
Parameters
URL Description
property (Required) Target property
site (Required) Target site
type The sensor type to gather readings from
e.g.
type=23
type=23,24
(See below for a list of calculated sensor types)
from Starting date/time range
to Ending date/time range
Response 
{
  "labels": ["2023-01-17T00:00:00+10:30:00", "2023-01-17T00:30:00+10:30:00"],
  "datasets": [
    {
      "id": 123250,
      "name": "Delta T",
      "typeId": 24,
      "typeName": "Delta T",
      "data": [9.549985, 10.345706],
      "valueType": 5
    }
  ]
}

[GET] /readings/latest

Get latest readings for a site.

Request:

https://api.greenbrain.ag/readings/latest?type=23,24&property=19&site=2909
Parameters
URL Description
property (Required) Target property
site (Required) Target site
type The sensor type to gather readings from
e.g.
type=23
type=23,24
(See below for a list of sensor types)
Response 
{
  "datasets": [
    {
      "id": 59871,
      "name": "Average",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [18.1],
      "latest": "2023-02-06T18:00:00+11:00",
      "upToDate": true,
      "valueType": 2
    }
  ]
}

[GET] /readings-daily

Get daily readings for a site.

Request:

https://api.greenbrain.ag/readings-daily?from=2023-01-17&to=2023-01-18&type=10,13&property=19&site=2909
Parameters
URL Description
property (Required) Target property
site (Required) Target site
type The sensor type to gather readings from
e.g.
type=10
type=4,6,10
(See below for a list of available sensor types)
from Starting date/time range
e.g. from=2022-01-01
(See below for supported date/time formats)
to Ending date/time range
e.g. to=2022-01-02
(See below for supported date/time formats)
Response 
{
  "labels": ["2023-01-16T00:00:00+10:30:00", "2023-01-17T00:00:00+10:30:00"],
  "datasets": [
    {
      "id": 16621,
      "name": "Minimum",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [25.952, 27.84],
      "valueType": 1
    },
    {
      "id": 16622,
      "name": "Average",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [27.834, 28.638],
      "valueType": 2
    },
    {
      "id": 16623,
      "name": "Maximum",
      "typeId": 10,
      "typeName": "Air Temperature",
      "data": [28.612, 29.223],
      "valueType": 3
    },
    {
      "id": 16630,
      "name": "Minimum",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [11.3, 11.04]
    },
    {
      "id": 16631,
      "name": "Average",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [12.49, 12.26],
      "valueType": 1
    },
    {
      "id": 16632,
      "name": "Maximum",
      "typeId": 13,
      "typeName": "Dew Point Temperature",
      "data": [13.4, 13.37],
      "valueType": 3
    }
  ]
}

[GET] /readings-daily/calculated

Get daily calculated readings for a site.

Request:

https://api.greenbrain.ag/readings-daily/calculated?from=2023-01-01&to=2023-01-18&type=23,24&property=19&site=2909
Parameters
URL Description
property (Required) Target property
site (Required) Target site
type The sensor type to gather readings from
e.g.
type=23
type=23,24
(See below for a list of calculated sensor types)
from Starting date/time range
to Ending date/time range
Response 
{
  "labels": ["2023-01-16T00:00:00+10:30:00", "2023-01-17T00:00:00+10:30:00"],
  "datasets": [
    {
      "id": 123250,
      "name": "Delta T",
      "typeId": 24,
      "typeName": "Delta T",
      "data": [9.549985, 10.345706],
      "valueType": 5
    }
  ]
}

Reference

Supported date/time formats:

info
"2022-01-01"
"2022-01-01 09:00:00"
"2022-01-01T09:00:00Z"
"2022-01-01T09:00:00+10:30"

Sensor data types:

info
2 - Soil Moisture Content (%)
3 - Soil Salinity (dS/m)
4 - Soil Temperature (ºC)
5 - Soil Moisture Tension (kPa)
6 - Rainfall (mm)
8 - Wind Speed (m/s)
10 - Air Temperature (ºC)
11 - Relative Humidity (%)
21 - Wind Direction (º)
22 - Solar Radiation (W/m^2)
33 - Wind Speed (km/h)
35 - Leaf Wetness (mV)
52 - Air Temperature (Canopy)
53 - Relative Humidity (Canopy)
106 - Soil EC (Pore Water) (mS/m)

Calculated Sensors:

info
23 - Dew Point
24 - Delta T
25 - Chill Units
26 - Daylight (hrs)
27 - Degree Days
28 - Frost Hours (Hrs)
32 - Evapotranspiration (mm)
73 - Chill Hours (Hrs)

Value Types:

info
1 - Minimum
2 - Average
3 - Maximum
4 - Raw
5 - Computed