Samples API

The Samples API allows the historical samples for a Site to be queried, created and deleted.

HTML Method	URI	Action
GET	/sites/{SITE_ID}/samples	Get Sample Data for a Site
POST	/sites/{SITE_ID}/samples	Create Sample Data to a Site
DELETE	/sites/{SITE_ID}/samples	Delete Sample Data from a Site

Get Sample Data

URI Parameters: SITE_ID

Additional Optional URI Parameters:

Parameter	Type	Description	Example
startTime	ISO 8601	First sample time will be >= Date/Time	2019-06-30T22:00:00+10:00
endTime	ISO 8601	Last sample time will be < Date/Time	2020-12-01T08:30:00+10:00
limit	Integer	Maximum number of samples to return	10
fields	String	Data fields to return [1]	A5,X3,X10
order	String	Time order to return (Asc or Desc) [2]	Desc
timezone	String	Timezone to return time values in [3]	Australia/Sydney

[1]	Defaults to all logged fields for the Site. Fields can also be specified using their name from the Config. e.g. “FlowRate” instead of X1

[2]	“Asc” for Ascending order , “Desc” for Descending order. Default is “Asc”

[3]	Defaults to the Site’s timezone. If the startTime or endTime parameters do not explicitly include a timezone then this timezone will be used when interpreting those values. “/” character must be encoded as %2F.

Parameter Examples:

/sites/1000/samples?startTime=2019-01-01T00:00:00Z&limit=500&order=Asc&timezone=Australia%2FAdelaide

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' 'https://www.telemetry.net.au/api/v1/sites/1000/samples?startTime=2019-01-01T00:00:00Z&limit=500'

Returns: This returns the selected samples in the following format.

{
        "sampleCount":3,
        "sampleDesc":
        {
                "0": { "field":"X1", "name":"Flow", "units":"L/S" },
                "1": { "field":"X2", "name":"Level", "units":"%" }
        },

        "samples":
        [
                { "time":"2019-12-10T17:17:40+10:00", "0":0.5, "1":90 },
                { "time":"2019-12-10T17:17:45+10:00", "0":0.5, "1":90 }
                { "time":"2019-12-10T17:17:50+10:00", "0":0.5, "1":90 }
        ]
}

sampleDesc: Is a description of the fields in each sample. For each index 0 to n of data in a sample this specifies the raw field stored in the database as well as the name and units for the field (as defined in the Config).

samples: This is an array of samples. “time” specifies the timestamp of the sample in ISO 8601 format in the timezone requested or the Site’s timezone, following this the sample values are given along with their index into the sampleDesc mentioned above. So in this example each sample has Flow=0.5L/S and Level=90%.

Notes on Timezones:

When specifying the startTime and endTime parameters in ISO 8601 format it can be tricky dealing with daylight savings time. For example if you are using the Australia/Sydney timezone, to request data from January to May you would need to specify 2 different TZ offsets as below:

startTime=2020-01-01T00:00:00+11:00
endTime=2020-05-01T00:00:00+10:00

To simplify this you can pass the timezone parameter to define what timezone you are using and then if the time parameters do not contain zone information then the specified timezone will be used, e.g.:

timezone=Australia/Sydney
startTime=2020-01-01T00:00:00
endTime=2020-05-01T00:00:00

If you don’t want daylight savings adjusted timestamps in the sample data then set the timezone to UTC

Create Sample Data

URI Parameters: SITE_ID

HTML Method: POST

POST Data: JSON format specifying the sample data. The format should follow the example above, however sampleDesc should normally specify only either the “field” or “name” parameter and the “units” field is ignored.

Example:

curl -X POST -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' --data '{ "sampleCount":1, "sampleDesc": { "0": { "field":"X1" }, "1": { "field":"X2" } }, "samples":[{ "time":"2019-12-10T17:17:40+10:00", "0":0.5, "1":90 },]}' https://www.telemetry.net.au/api/v1/sites/1000/samples

Returns: The number of samples successfully created.

Note

API Key must have write access

Delete Sample Data

URI Parameters: SITE_ID

Additional Optional URI Parameters:

Parameter	Type	Description	Example
startTime	ISO 8601	First sample deleted will be >= Date/Time	2019-06-30T22:00:00+10:00
endTime	ISO 8601	Last sample deleted will be < Date/Time	2020-12-01T08:30:00+10:00
limit	Integer	Maximum number of samples to be deleted	10

HTML Method: DELETE

Example:

curl -X DELETE -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' https://www.telemetry.net.au/api/v1/sites/1000/samples?startTime= 2019-6-30T22:00:00Z&sampleCount=10

Returns: The number of samples deleted.

Note

• startTime and/or endTime must be specified
• API Key must have write access