Sites API

The Sites API enumerates available Sites, create new Sites and modifies existing Sites.

HTML Method	URI	Action
GET	/sites	Get a list of all available Sites
GET	/sites/{SITE_ID}	Get detailed information for a given Site
POST	/sites	Create a new Site
PUT	/sites/{SITE_ID}	Modify an existing Site
DELETE	/sites/{SITE_ID}	Delete an Existing Site

Get Available Sites

URI Parameters: None

Additional Optional URI Parameters:

Parameter	Type	Description	Example
localeID	Integer	Only return Sites in the Locale	123
regExp	String	Filter Sites by Regular Expression [1]	^Test.?

[1]	Matches Site name using a regular expression. Some regular expression characters may need to be escaped. For example [0-9] may need to be written as \[0-9\] on Unix based operating systems

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' https://www.telemetry.net.au/api/v1/sites

Returns: If the call succeeds, returns a list of Sites in JSON format. The Site information returned is a subset of the information returned by the “Get Site Details” call below. The following example shows the current fields returned.

{
        "siteCount":2,
        "sites":
        [
                {
                        "id":1000,
                        "name":"Site 1",
                        "localeID":100
                },
                {
                        "id":1001,
                        "name":"Site 2",
                        "localeID":100
                }
        ]
}

Field	Description
id	Internal unique identifier for the Site
name	Name of Site
localeID	Internal unique identifier for the Locale that this Site belong to (0 if not in a Locale)

Get Site Details

URI Parameters: SITE_ID

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' https://www.telemetry.net.au/api/v1/sites/1000

Returns: If the call succeeds, returns detailed information about the Site in JSON format. The following example shows the current fields returned.

{
        "id":1000,
        "name":"Test Site",
        "localeID":100,
        "localeLabel":"Irrigation",
        "serialNumber":300000,
        "latitude":-27.215191,
        "longitude":153.094323,
        "configID":5,
        "description":"",
        "companyID":1,
        "timezone":"Australia/Brisbane",
        "tag":"",
        "sampleTime":60,
        "connectTime":600
}

Field	Description
id	Internal unique identifier for the Site
name	Name of Site
localeID	Internal unique identifier for the Locale that this Site belong to (0 if not in a Locale)
localeLabel	An optional label that identifies a Site within a Locale
serialNumber	Serial number of Agent installed at the Site
latitude	GPS Coordinate of Site
longitude	GPS Coordinate of Site
configID	Internal unique identifier for the Config being used for this Site
description	Description of the Site
companyID	Internal unique identifier for the Company this Site belong to
timezone	The Timezone for the Site
tag	A Tag string which can be used to identify the Site or groups of Sites
sampleTime	The normal sampling interval used for the Site in seconds
connectTime	The normal interval for communicating and sending samples to the server

Create New Site

URI Parameters: None

HTML Method: POST

POST Data: JSON format specifying the parameters for the new Site. See the table below for allowed parameters. The “id” field is ignored if present, a new unique ID will be assigned to the newly created Site.

Valid Fields:

Field	Description
name	Name of the new Site [Required]
configID	The ConfigID to assign to the Site [Required]
localeID	The LocaleID of the Locale to put the Site in
localeLabel	The Label to use within the Locale
serialNumber	The serial number of the Agent to assign to the Site if known
latitude	Location of Site if known
longitude	Location of Site if known
description	Description of the Site
companyID	The CompanyID to use if the API Key has rights to multiple companies
timezone	Timezone for the Site location. e.g. Australia/Sydney
tag	Tag to assign to the new Site
sampleTime	Sampling rate in seconds. If not specified the default defined in the Config will be used
connectTime	Connect interval in seconds. If not specified the Config default will be used

Example:

curl -X POST -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' --data '{"name":"Test Site","localeID":100,"latitude":-27.215191,"longitude":153.094323,"configID":5}' https://www.telemetry.net.au/api/v1/sites

Returns: If the call succeeds, detailed information about the Site created is returned in JSON format.

Note

API Key must have write access

Modify Existing Site

URI Parameters: SITE_ID

HTML Method: PUT

PUT Data: JSON format specifying the parameters to change for the specified Site. Allowable parameters are identical the the “Create New Site” call above.

Example:

curl -X PUT -H "Content-Type: application/json" -H 'X-Api-Key: API_KEY' --data '{"name":"Test","localeID":100,"latitude":-27.215191,"longitude":153.094323,"configID":5}' https://www.telemetry.net.au/api/v1/sites/1000

Returns: If the call succeeds, detailed information about the Site is returned in JSON format.

Note

API Key must have write access

Delete Site

URI Parameters: SITE_ID

HTML Method: DELETE

Example:

curl -X DELETE -H 'X-Api-Key: API_KEY' https://www.telemetry.net.au/api/v1/sites/1000

Returns: If the call succeeds, detailed information about the Site deleted is returned in JSON format.

Warning

This cannot be undone!!
All data associated with the Site will be deleted, this includes Samples, Alarms, Notes, Logs and Profile.

Note

API Key must have write access