Point Weather Forecast API Guide

Summary:

This document explains how to access the Point Weather Forecast (derived from BoM's ADFD - Australian Digital Forecast Database) data hosted on the Senaps platform. In particular this document focuses on using the THREDDS Data Manager (TDM) API provided by Eratos Senaps to extract specific point locations and return the data as JSON time series.

Prerequisites:

• Authorisation and license agreement. You can purchase a subscription through our AgData Shop. 

• An Understanding of how BoM ADFD data is structured. Please see the BoM ADFD User Guide document for details.
  
  
  

Introduction

Senaps provides an API called TDM (THREDDS Data Manager) which allows for extracting point (longitude, latitude) location forecasts for ADFD data, sometimes referred to as 'drilling' the dataset.

TDM is a REST API with JSON encoded responses. 

Senaps provides a drill operation as part of the TDM API to provide an easy to use end-point for drilling gridded datasets. 

Authentication

All Ag Climate Data 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.

ADFD data availability

Currently the ADFD data is being synchronised from the BoM twice daily at 00:00Z (10am AEST) and 12:00Z (10pm AEST).

The latest set of files will always be available in the THREDDS data server catalog at consistent URLs. 

The listing of latest files is available as a web page:
https://senaps.eratos.com/thredds/catalog/org_catalogs/csiro/BoM_ADFD/latest/catalog.html

and also as an XML catalog:

https://senaps.eratos.com/thredds/catalog/org_catalogs/csiro/BoM_ADFD/latest/catalog.xml

ADFD Variables

Drilling ADFD - Example Test 

As an example, we can use the interactive API documentation to test the drill operation.  You will need a HTTP Bearer Authentication token to run through these steps, see above. 

The TDM drill API operation is documented here: https://senaps.eratos.com/api-docs/#/.  To access the correct API select THREDDS Data Manager API from the drop down box at the top left.  Use the Authorise button to set the HTTP Bearer Authentication token obtained above.

Open

ie. if we want to drill the MaxT_SFC variable we need to:

Step 1: Find the dataset path of the latest MaxT ADFD forecast from the table above.

Step 2: Use the APIDocs to query the drill API 

• Expand the GET /drill operation, by clicking on the 'GET' button.

• Click the "Try it out" button to allow data to be entered 

• Fill in the mandatory path, longitude, latitude and variable fields as shown below (full dataset path is /csiro/BoM_ADFD/latest/IDZ71002_AUS_MaxT_SFC.nc)

Open

Step 3: Execute request

Press the Execute button.  

If the request is successful the status code will be 200 and the response will contain the JSON encoded response similar to below.  The values for the slices at the nearest grid cell are contained in the 'results' array. The values are extracted directly from the netCDF file and are not manipulated at all by the drill operation.

Directly using the API endpoint:

(Most of this can be deduced from the API Docs example above.)

a. The URL for the request is https://senaps.eratos.com/tdm/drill 
b. The request method is GET
c. Every request needs authenticating. Using the HTTP Bearer Authentication header. The header must be of the format "Authorization: Bearer <token>"
d. Example parameters can be seen in the api-docs and the above example.

The equivalent call to above is:

https://senaps.eratos.com/tdm/drill?path=%2Fcsiro%2FBoM_ADFD%2Flatest%2FIDZ71002_AUS_MaxT_SFC.nc&longitude=147.3&latitude=-42.99&variable=MaxT_SFC

The Docs provide examples of making the API calls using the common command line tool curl.

API fair usage limits

To maintain quality and low cost service the ADFD-P product includes a fair use policy for API requests.

A single subscription of the ADFD-P product entitles the subscriber to 1000 requests per day to the TDM /drill end-point described in this document.

Please contact the AgData Shop to discus options for higher usage.