Athena IR-Tech Transp-IR

API Specification Doc

Revision	Date	Author	Description
1.0	2023 May 30	Buddhika Biyagama	Initial draft
1.1	2023 Aug 17	Jay Holata	Revision
1.2	2023 Sep 5	Jay Holata	Final Revision
1.3	2023 Oct 26	Buddhika	Add new endpoints

Content

1. Getting Started 4

2. Basic Information 4

Authorization 4

To access any of our API resources, you must provide the following header parameters. 4

Pagination 5

Athena Organisational and Data Structure 5

3. Get Site Information 6

HTTP request 6

Query parameters 6

https://api.staging.athenairtech.com/v1/site?uid=SI-APM 6

Response body 6

4. Get Site User Inputs 8

5. Create Site User Inputs 9

HTTP request 9

Request Body Parameters 9

7. Get Block User Input 12

8. Create Block User inputs 14

HTTP request 14

Request Body Parameters 14

Example Request 15

9. Get Device Info 17

10. Get Device Readings 22

11. Get Device Calculated Values 24

Getting Started

To access the API as a developer you’ll need to retrieve your customer’s unique Client ID from the Transp-IR dashboard of your customer. Only customers who have purchased the Precision level subscription will have a Client ID assigned to them.

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

An Athena Transp-IR User Account for you that lets you view the Athena Transp-IR Staging environment using our interactive front-end, to help you understand the data structure and presentation.
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 Athena Staging environment. Beyond this, you’ll need to have the Athena Admin at your client confirm in writing (email is best) directly to admin@athenairtech.com that they approve the sharing of their data with you. They should include:

The Organisation Name in Athena from which their data can be shared;
The company to which access to the data can be granted (your company); 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 Athena, 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

The URL for the production site is https://api.athenairtech.com

For testing, the URL for the staging environment where testing occurs is https://api.staging.athenairtech.com/v1

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 token.

Authorization

To access any of our API resources, you must provide the following header parameters.

Name	Required	Description
x-client-id	required	Your unique client identifier
x-api-key	required	Your API Key

Pagination

To paginate, you could provide the following header parameters.

Name	Required	Description
x-limit	optional	Each request can contain up to 500 records
x-next-page-key	optional	Response header x-next-page-key is used to fetch the next page of results.

Athena Organisational and Data Structure

Athena has a defined structure for customers, their sites, blocks and related devices and seasonal data. Each customer is structured as follows:

Organisation - Customer company

Site A - A geographical location

Site B - 2nd location

Site C - xxx additional locations

Note: For organisations that are consultants that have multiple clients, the consultant is considered the organisation and each client is then considered a site.

Block 1 - Any area within a site that is usually a specific crop or cultivar or defined by a zoned irrigation valve.

Block 2 - 2nd block

Block 3 - n - additional blocks

Device 1 - Athena field units that record the data

Device 2 - 2nd device

Device 3 - n - additional devices in the block

3. Get Site Information

This returns general information about a site. An organisation can have multiple geographical locations that are considered sites within Athena.

HTTP request

GET https://api.athenairtech.com/v1/site

Query parameters

Name

Required

Description

uid

string

required

Athena Site UID. Site UID is copied from the Transp-IR dashboard.

To get the UID from the dashboard click on Sites . Click on the copy button next to the Site-UID for the site you are accessing. This same concept of UID and copying also exists in the dashboard for blocks and devices.

https://api.staging.athenairtech.com/v1/site?uid=SI-APM

Response body

If successful, the response body contains the information for the Site including the list of blocks in the site.

{

"address" : {

"state" : "South Australia",

"postal_code" : "5064",

"geolocation" : {

"lng" : "138.6338539",

"lat" : "-34.9687753"

"administrative_area_level_2" : "Mitcham",

"country_long_name" : "Australia",

"url" : "https://maps.google.com/?cid=1081768075369040080",

"address" : "Urrbrae SA 5064, Australia",

"administrative_area_level_2_long_name" : "City of Mitcham",

"administrative_area_level_1" : "SA",

"administrative_area_level_1_long_name" : "South Australia",

"postal_code_long_name" : "5064",

"country" : "AU",

"locality" : "Urrbrae",

"locality_long_name" : "Urrbrae"

"block" : [

{

"crop_variety" : "almond_sdad",

"block_season_year" : 2023,

"block_name" : "Almond Test Block",

"crop_species" : "almond",

"uid" : "BL-ASK"

{

"crop_variety" : "wine_grape_cabernet_sauvignon",

"block_season_year" : 2023,

"block_name" : "Grape Test Block",

"crop_species" : "wine_grape",

"uid" : "BL-ASJ"

{

"crop_variety" : "wine_grape_cabernet_sauvignon",

"block_season_year" : 2023,

"block_name" : "Citrus Test Block",

"crop_species" : "wine_grape",

"uid" : "BL-ASL"

}

"uid" : "SI-APM",

"time_zone" : "Australia/Adelaide",

"site_name" : "Demo Site"

}

4. Get Site User Inputs

Returns site user entered information for:

Rainfall
Notes

Only rainfall and notes are recorded at the site level as irrigation is specific to a block and grape sugar content is specific to those blocks that have a grape variety.

HTTP request

GET https://api.athenairtech.com/v1/site/readings

Query parameters

Name	Required	Description
uid string	required	Athena site UID
type date	required	RFL - Rainfall NTE - Notes
from date	required	Date format is “YYYY-MM-DD”
to date	optional	Date format is “YYYY-MM-DD”

Example Request

GET /readings?uid=B_AVM&type=RFL&from=2023-07-15

Response body

If successful, the response body contains an array of data.

{

"data": [

{

"created_at": "2023-07-15T08:00:06.000+09:30",

"amount": 200, }]}

5. Post Site rainfall and user notes

Rainfall
Notes

HTTP request

POST https://api.athenairtech.com/v1/site/readings

Request Body Parameters

Name

Required

Description

uid

string

required

Athena site UID

type

date

required

RFL - Rainfall
NTE - Notes

data

array

required

RFL

created_at

date

required

ISO Date format is “YYYY-MM-DD”

amount

object

required

{

"value": 2.2,

"unit": ”mm”, # mm or inc

}

NTE

created_at

date

required

ISO DateTime format is “YYYY-MM-DD hh:mm:ss”

title

string

required

content

text

required

Example Request

POST site/readings

{

"uid": “SI-ASK”,

"type": “RFL”,

"data": [{

"created_at": “2023-10-26 14:30:00”

"amount": {

"value": 10,

"unit": ”mm”,

}

{

"created_at": “2023-10-27 14:30:00”

"amount": {

"value": 20,

"unit": ”mm”,

}

]

}

Response body

If successful, the response body contains a success response.

{status: “ok”}

6. Get Block Info

Returns Block information.

HTTP request

GET https://api.athenairtech.com/v1/block

Query parameters

Name

Required

Description

uid

string

required

Athena block UID

Example Request

GET /block?uid=BL_AFG

Response body

If successful, the response body contains an instance of block.

{

"uid": "BL_AFG",

"site_name": "My Test Site",

"block_name": "Backyard",

"time_zone": "Australia/Adelaide",

"crop_variety": "wine_grape_shiraz",

"block_season_year": 2023,

7. Get Block User Input

Returns block user input for:

Irrigation
Grape sugar content
notes

A separate request must be made for each type of information for the block.

HTTP request

GET https://api.athenairtech.com/v1/block/readings

Query parameters

Name	Required	Description
uid string	required	Athena block UID
type date	required	IRT - Irrigation GSC - Grape sugar content (only applies if crop is winegrape) NTE - Notes
from date	required	Date format is “YYYY-MM-DD”.
to date	optional	Date format is “YYYY-MM-DD”

Example Request

GET /readings?uid=BL_AVM&type=irrigation&from=2023-07-15

Response body

If successful, the response body contains an array of data.

{

"data": [

{

"created_at": "2023-07-15T08:00:06.000+09:30",

"amount": 200,

]}

8. Post Block irrigation, grape sugar content and notes

Irrigation
Grape sugar content
notes

HTTP request

POST https://api.athenairtech.com/v1/block/readings

Request Body Parameters

Name

Required

Description

uid

string

required

Athena block UID

type

date

required

IRT - Irrigation
GSC - Grape sugar content (only applies if crop is winegrape)
NTE - Notes

data

array

required

GSC

created_at

date

required

ISO DateTime format is “YYYY-MM-DD hh:mm:ss”

amount

object

required

{

"value": 2.2,

"unit": ”bx”, # bx or be

}

bx - Brix ,

be - Baume

NTE

created_at

date

required

ISO DateTime format is “YYYY-MM-DD hh:mm:ss”

title

string

required

content

text

required

IRT (As depth)

created_at

date

required

ISO DateTime format is “YYYY-MM-DD hh:mm:ss”

amount

object

required

{

"value": 2.2,

"unit": ”mm”,

}

mm - Millimeters

inc - Inches

IRT (As flow rate)

Irrigated area should be defined in the Block
Pump flow rate should be defined in the Block
Duration of irrigation can be defined as single value or start and end time

created_at

date

required

ISO DateTime format is “YYYY-MM-DD hh:mm:ss”

duration

object

required

Duration as a Single Value

{

"value": 10,

"unit": ”sec”,

}

min - Minutes

sec - Seconds

hr - Hours

Duration with Start and End Times:

{

"start_time": “15:45:00”,

"end_time": “15:55:00”,

}

ISO time format “hh:mm:ss”

3:45 PM: "15:45:00"

8:30:25 AM: "08:30:25"

Example Request

POST /block/readings

{

"uid": "BL-APU",

"type": "IRT",

"data": [

{

"created_at": "2023-10-27 14:30:00",

"amount": {

"value": 10,

"unit": "inc"

}

{

"created_at": "2023-10-28 14:30:00",

"duration": {

"value": 2,

"unit": "hr"

}

{

"created_at": "2023-10-29 14:30:00",

"duration": {

"start_time": "15:45:00",

"end_time": "17:45:00"

}

]

}

Response body

If successful, the response body contains a success response.

{status: “ok”}

9. Get Device Info

Returns the following information about a device within a block

Geolocation
Device short UID
Grape variety name
Device version
Site name
Block name
Season start date for this device
Current phenological stage
Species (Crop) UID
Device ID - unique 13 digit device ID
Season year
Time zone
Name - device name assigned by the user

For each device the settings are also returned that govern how the data is displayed on the Crop Water Index graph. This information is found in the dashboard at Settings / CWI Thresholds.

Crop Water Index (CWI) - This is generated once a day and represents the blue line on the graph.

Chart Thresholds and Phenological Stages - Each crop has defined phenological stages with start and end dates as defined by the user. The green optimal plant water status zone on the CWI graph is represented by the thresholds in this section. Three “chart thresholds” are defined for each set of phenological stages. They are:

Upper limit of green zone
Lower limit of green zone
Red line

Below each set of chart thresholds are the names of the starting and ending phenological stages for the chart thresholds.

The next section of information is about the units of measure that are defined in the dashboard in Settings / Units for each attribute that is displayed on the graph. The following attributes have their units of measure definable by the user:

CWI - no unit defined
VPD - vapour pressure deficit
IR1AT - infrared sensor 1 canopy temperature
IR2AT - infrared sensor 2 canopy temperature
T_AMB - Ambient temperature
RH - Relative humidity
SOLAR_RAD - solar radiation

HTTP request

GET https://api.athenairtech.com/v1/device/

Query parameters

Name

Required

Description

uid

string

required

Athena block device UID

Example Request

GET device/?uid=BD_AVM

Response body

If successful, the response body contains the device metadata including settings that guide the display of the device information on the CWI graph and dashboard.

{

"geolocation" : {

"lng" : "138.45255",

"lat" : "-35.28148"

"uid" : "BD-AVR",

"variety_name" : "Cabernet Sauvignon",

"device_version" : "v1.0.0",

"site_name" : "Demo Site",

"block_name" : "Grape Test Block",

"season_start_date" : "2023-08-02T06:52:31.467+09:30",

"current_phenological_stage" : "budburst - flowering",

"species_uid" : "wine_grape",

"species_name" : "Wine Grape",

"variety_uid" : "wine_grape_cabernet_sauvignon",

"phenological_stages" : [

"budburst",

"flowering",

"veraison",

"harvest"

"installed_at" : "2023-08-02T09:30:00.000+09:30",

"properties" : {

"calculated" : [

{

"frequency" : "Once per day",

"thresholds" : [

{

"chart_thresholds" : [

"0.3",

"0.7",

"2.0"

"phenological_stages" : [

"budburst",

"flowering"

]

{

"chart_thresholds" : [

"0.3",

"0.45",

"0.65"

"phenological_stages" : [

"flowering",

"veraison"

]

{

"chart_thresholds" : [

"0.3",

"0.45",

"0.65"

"phenological_stages" : [

"veraison",

"harvest"

]

}

"attribute" : "cwi",

"description" : "Crop Water Index",

"unit" : ""

{

"frequency" : "Once per day",

"attribute" : "vpd",

"description" : "Vapor Pressure Deficit",

"unit" : "kPa"

}

"readings" : [

{