Schedule API

The Schedule API allows the Scheduler Entries for a Site to be queried, and the resulting scheduled events to by computed.

HTML Method	URI	Action
GET	/sites/{SITE_ID}/schedule	Get Schedule Entries for a Site
GET	/sites/{SITE_ID}/get_events	Get Scheduled Events for a given time range
GET	/sites/{SITE_ID}/get_daily_scheduled	Compute total scheduled time for each day

Get Schedule Entries

URI Parameters: SITE_ID

Additional Optional URI Parameters:

Parameter	Type	Description	Example
timezone	String	Timezone to return time values in [1]	Australia/Sydney

[1]	Defaults to the Site’s timezone. “/” character must be encoded as %2F.

Parameter Examples:

/sites/1000/schedule?timezone=Australia%2FBrisbane

HTML Method: GET

Example:

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

Returns: This returns the Schedule Entries in the following format.

{
        "id":3,
        "outputsTurnedOff":0,
        "outputsTurnedOn":0,
        "master":"auto",
        "globalOff":false,
        "hasRained":false,
        "rainForecast":false,

        "entryCount":2,
        "entries":
        [
                {
                        "id":233,
                        "description":"Oval 1",
                        "startTime":"2020-04-14T09:40:00+10:00",
                        "duration":300,
                        "outputID":1199,
                        "outputName":"Oval Sprinklers ",
                        "repeatMode":"weeklyOnDays",
                        "repeatParameter":3,
                        "disabled":false,
                        "endDate":"2020-08-19"
                },
                {
                        "id":234,
                        "description":"Wicket",
                        "startTime":"2017-06-13T05:00:00+10:00",
                        "duration":600,
                        "outputID":119,
                        "outputName":"Wicket Sprinklers",
                        "repeatMode":"weeklyOnDays",
                        "repeatParameter":12,
                        "disabled":false,
                        "endDate":""
                },
        ]
}

The root level fields are global parameters for the Site’s Schedule. The fields are defined below:

Field	Description
id	Internal unique identifier for the Schedule
outputsTurnedOff	A set of bits that define what outputs are permanently off (32-bits for 32 outputs)
outputsTurnedOn	A set of bits that define what outputs are permanently on (32-bits for 32 outputs)
master	The current state of the Master switch. Possible values are: on, off or auto [2]
globalOff	The current state of the Global switch (boolean) [2]
hasRained	True if the Schedule is currently disabled due to recent rainfall (boolean) [2]
rainForecast	True if the Schedule is currently disabled due to forecast rainfall (boolean) [2]

[2]	(1, 2, 3, 4) These fields are optional if the Schedule is setup to use these features.

The Entry fields are defined below:

Field	Description
id	Internal unique identifier for the Schedule Entry
description	A description of the entry
startTime	The date/time when the schedule entry starts
duration	The duration in seconds
outputID	Internal unique identifier for the output definition
outputName	Name of the output or group
repeatMode	Repeat Mode (see table below)
repeatParameter	Repeat Parameter, depends on the Repeat Mode (see table below)
disabled	True if the Entry has been disabled (boolean)
endDate	If specified the date when the Schedule ends

Repeat Mode definitions:

Repeat Mode	Description	Repeat Parameter
none	Occurs once only at the specified start date/time	Unused
daily	Occurs every day at the specified start time	Unused
weekdays	Occurs every week day at the specified start time	Unused
everyNthDay	Occurs every ‘n’ days at the specified start time	n
everyNthHour	Occurs every ‘n’ hours	n
weeklyOnDays	Occurs on the specified days of the week	day bit-field [3]
weekly	Occurs every week on the same day as the start date	Unused
monthly	Occurs every month on the same day as the start date	Unused
yearly	Occurs yearly on the same date as the start date	Unused

[3]	A set of 7 bits for each day of the week. Bit 0=sunday, 1=monday .. 6=saturday

Get Scheduled Events

A Schedule Entry defines the lifetime of the Entry and how it will repeat over that time. A Scheduled Event is the result of a Scheduled Entry, e.g. a Schedule Entry that is set to repeat every Monday and Tuesday for 4 weeks will result in 8 Scheduled Events ocurring.

URI Parameters: SITE_ID

Required URI Parameters:

Parameter	Type	Description	Example
startTime	ISO 8601	First Event time will be >= Date/Time	2019-06-30T22:00:00+10:00
endTime	ISO 8601	Last Event time will be < Date/Time	2020-12-01T08:30:00+10:00

Optional URI Parameters:

Parameter	Type	Description	Example
timezone	String	Timezone to return time values in	Australia/Sydney
collapseGroups	String	Don’t return expanded output groups [4]	Australia/Sydney

[4]	By default Events will be returned for groups as well as all the individual members of that group. If you only wish to see a top-level view of the Events then specify this parameter.

Parameter Examples:

/sites/1000/get_events?startTime=2020-07-01&endTime=2020-08-01

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' 'https://www.telemetry.net.au/api/v1/sites/1000/scheduled_events?startTime=2020-07-01&endTime=2020-08-01'

Returns: Scheduled Events for the given time range in the following format:

{
        "eventCount":2,
        "events":
        [
                {
                        "id":1234,
                        "startTime":"2020-07-01T00:00:00+10:00",
                        "duration":9000,
                        "onTime":3000,
                        "outputID":120,
                        "outputName":"Oval Sprinklers",
                },
                {
                        "id":1235,
                        "startTime":"2020-07-01T01:30:00+10:00",
                        "duration":600,
                        "onTime":600,
                        "outputID":121,
                        "outputName":"Wicket Sprinklers",
                },
        ]
}

Field	Description
id	Internal unique identifier for the Schedule Entry that caused this Event
startTime	The start time of the Event
duration	The duration of the Event in seconds
onTime	The total on-time for the event in seconds [5]
outputID	Internal unique identifier for the output definition
outputName	Name of the output or group

[5]	The onTime specifies the total time that the Event has turned on the output. For groups this may be less than the Event duration as staggered groups allow for a delay between the members of the groups, so there are rest periods where the output is turned off.

Get Daily Scheduled Time

URI Parameters: SITE_ID

Required URI Parameters:

Parameter	Type	Description	Example
startTime	ISO 8601	First day returned will be this date	2020-07-01T00:00:00+10:00
endTime	ISO 8601	Last day returned will be this date	2020-08-01T00:00:00+10:00

Optional URI Parameters:

Parameter	Type	Description	Example
timezone	String	Timezone to return time values in	Australia/Sydney

Parameter Examples:

/sites/1000/get_daily_scheduled?startTime=2020-07-01&endTime=2020-08-01

HTML Method: GET

Example:

curl -H 'X-Api-Key: API_KEY' 'https://www.telemetry.net.au/api/v1/sites/1000/get_daily_scheduled?startTime=2020-07-01&endTime=2020-08-01'

Returns: The total time scheduled in seconds for each day in the given range in the following format:

{
        "dayCount":31,
        "days":
        [
                {"date":"2020-07-01","onTime":3000},
                {"date":"2020-07-02","onTime":9600},
                {"date":"2020-07-03","onTime":3000},
                {"date":"2020-07-04","onTime":0},
                {"date":"2020-07-05","onTime":2400.0},

                {"date":"2020-07-26","onTime":2400.0},
                {"date":"2020-07-27","onTime":3600.0},
                {"date":"2020-07-28","onTime":10800},
                {"date":"2020-07-29","onTime":3000},
                {"date":"2020-07-30","onTime":9600},
                {"date":"2020-07-31","onTime":3000}
        ]
}