Documentation

Getting Started

  1. To access the API as a developer, you will have a Green Brain User Account setup with API access. When this has been setup, you will receive a ‘Welcome to Green Brain!’ email with login credentials. This account provides access to your own account, where you can login to the Green Brain web app to see different data formats, check latest readings and see which properties you have access to.

  2. You will also be sent a unique client identifier and API Key (separately to the credentials provided in Step 1).

info
If you haven’t received all of these pieces of information, please contact service@greenbrain.ag with the following information:
  • Organisation: [YOUR ORGANISATION]
  • Account: [YOUR USERNAME or EMAIL]
  • IP Address: [YOUR PUBLIC IP ADDRESS]
  • The missing information (Green Brain Account Access, API Key or Unique Client Identifier)
  1. In order to be granted access to the data from an existing Green Brain user, the user (i.e. the owner of the data, hardware and property being monitored) will need to email Green Brain (service@greenbrain.ag) providing the following information:
  • System Name in Green Brain to be shared
  • Organisation to be granted access
  • Duration of Access (if nothing is specified, a default duration of 1 year will be used).

Once you have completed steps 1 and 2 above, you will have access to the Green Brain API to begin the development process. To support this, your account will have access to a demonstration system that includes most of the common data types found in Green Brain.

Basic Information

URL: https://api.greenbrain.ag

Authorization

To access any of our API resources, you must first request for an access token.

[GET] /auth/token

Request:

Header Description
x-client-id Your unique client identifier
x-api-key Your purpose API Key

Response:

{
  "token": "xxxx.yyyyy.zzzzz",
  "expiry": 1680311692
}
info
Tokens will expire after 30 days

Readings

Below contain API resources relating to sensor readings.

info
Each request enables you to retrieve data for a 24-hour period.

[GET] /readings

Get minute readings for a site.

Request:

e.g. /readings?property=123&site=123&from=2022-01-01&to=2022-01-02&type=10

Authorization:

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

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-01 09:00:00", "2023-01-01 09:30:00"],
  "datasets": [
    {
      "id": 100,
      "name": "10cm",
      "typeId": 10,
      "typeName": "Temperature",
      "data": [20.124, 21.5]
    }
  ]
}

[GET] /readings/calculated

Get minutely calculated readings for a site.

Request:

e.g. /readings/calculated?property=123&site=123&from=2022-01-01&to=2022-01-02&type=23

Authorization:

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

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-01 09:00:00", "2023-01-01 09:30:00"],
  "datasets": [
    {
      "id": 100,
      "name": "10cm",
      "typeId": 10,
      "typeName": "Temperature",
      "data": [20.124, 21.5]
    }
  ]
}
info
Supported date/time formats:
- "2022-01-01"
- "2022-01-01 09:00:00"
- "2022-01-01T09:00:00Z"
- "2022-01-01T09:00:00+10:30"
info
Sensor data types:
- 2 - Soil Moisture Content (%)
- 4 - Soil temperature
- 6 - Rainfall
- 10 - Air Temperature
- 11 - Relative Humidity
- 20 - Soil Water Content (%)
- 21 - Wind Direction
- 22 - Solar Radiation (W/m^2)
- 26 - Daylight Hours (Hrs)
- 33 - Wind Speed (km/hr)
- 35 - Leaf Wetness (mV)
- 52 - Air Temperature (Canopy)
- 53 - Relative Humidity (Canopy)
- 74 - Soil Moisture Tension - Watermark (kPa)
- 75 - Soil Moisture Tension - Malvic (kPa)
info
Calculated Sensors:
- 12 - Vapour Pressure Deficit (kPa)
- 14 - Frost Point Temperature (oC)
- 23 - Dew Point
- 24 - Delta T
- 25 - Chill Units
- 27 - Growing Degree Days
- 28 - Frost Hours (Hrs)
- 32 - Evapotranspiration (mm)
- 40 - Heat Load Index
- 73 - Chill Hours (Hrs)
- 102 - Kc
- 109 - Irrigation Pressure (kPa)
- 114 - Sap Flow (cm/hr)