API tutorial

This tutorial will get you up and running quickly with the API. Code snippets are in Python, however the same principles apply for other programming languages. Let's begin by testing the API in your browser. You can query metadata without an API key. For example, to get information about variables, type the following into your browser:

https://siloapi.longpaddock.qld.gov.au/variables

The response should look similar to this (formatted here for readability):

JSON

{
"data":[
{
    "name":"Daily rainfall",
    "units":"mm",
    "code":"daily_rain"
},
{
    "name":"Monthly rainfall",
    "units":"mm",
    "code":"monthly_rain"
},
...
]
}

However, most users will be interested in querying point data. To do this, you must first get an API key:

  1. Log in to SILO then hover over the icon in the navigation bar and select My API keys.
  2. Click the New API key button. Choose a name which will help you remember what you're using the key for. You can have up to 4 API keys.
  3. After you've created the API key it's immediately available for use. Note that requests for point data are subject to a download limit.

You can now query point data by typing the data request into your browser's address bar. For Example:

    https://siloapi.longpaddock.qld.gov.au/pointdata?apikey={YOUR_API_KEY}&start=20160101&finish=20160102&station=1001&format=json&variables=max_temp,min_temp

Replace {YOUR_API_KEY} with the alphanumeric key you obtained in step 3 above.

You should see a response which looks similar to this (formatted here for readability)


{
    "station": {
        "name": "OOMBULGURRI",
        "number": 1001,
        "longitude": 127.8456,
        "latitude": -15.1806,
        "elevation": 2.0
    },
    "data": [
        {
            "date": "2016-01-01",
            "variables": [
                {
                    "source": 13,
                    "value": 24.4,
                    "variable_code": "max_temp"
                },
                {
                    "source": 13,
                    "value": 17.3,
                    "variable_code": "min_temp"
                }
            ]
        },
        {
            "date": "2016-01-02",
            "variables": [
                {
                    "source": 13,
                    "value": 29.6,
                    "variable_code": "max_temp"
                },
                {
                    "source": 13,
                    "value": 15.5,
                    "variable_code": "min_temp"
                }
            ]
        }
    ]
}
    

If not, read the error message and ensure you have structured the request properly.

Now that we know the API is working, let's write a Python program to query it. We're going to use Python 3 and the requests module to download some data and query some metadata.


import requests

params = {
    'apikey': {YOUR_API_KEY},
    'format': 'json',
    'station': 1001,
    'start': '20160101',
    'finish': '20160102',
    'variables': 'max_temp,min_temp'
}

r = requests.get('https://siloapi.longpaddock.qld.gov.au/pointdata', params=params)
point_data = r.json()
print(point_data)

r = requests.get('https://siloapi.longpaddock.qld.gov.au/variables')
variables = r.json()
print(variables)
    

You can also obtain data using command line tools such as curl or wget.


#!/bin/bash

my_key="substitute your API key here"
api_url="https://siloapi.longpaddock.qld.gov.au"
begin="20160101"
end="20160105"

# Request maximum and minimum temperature data in JSON format at a grid location
lat="-30.00"
lon="135.00"
wget -O my_data -o my_log "$api_url/pointdata?lat=$lat&lon=$lon&apikey=$my_key&start=$begin&finish=$end&format=json&variables=max_temp,min_temp"

# Note: the data will be stored in the "my_data" file, and the wget logging information stored in the "my_log" file.

# Request vapour pressure data in CSV format at a station location
station="1018"
curl "$api_url/pointdata?station=$station&apikey=$my_key&start=$begin&finish=$end&format=csv&variables=vp"
    

That's it! We now recommend that you read the guide, which contains important information about the SILO Web API. For more details on the available resources, consult the reference.