Timers are represented as objects with the following fields

Name

Type

Read-Only

Required for "Add"

Comment

id

string

yes

no

Unique identifier for this timer

name

string

yes

no

Name of the show associated with this timer

device_id

integer

no

yes

Unique identifier for the TV Recording device associated with this timer (See Device)

channel_id

integer

yes

no

IceTV channel ID associated with this timer (See Channel)

show_id

integer

yes

IceTV show ID associated with this timer (See Show)

start_time

string

yes

no

Start time for this timer, formatted as per ISO 8601, expressed in UTC

duration_minutes

integer

yes

no

Duration of the timer in minutes

action

string

yes

no

Timer action

Forget	Timer needs to be deleted from the TV Recorder
Record	Record the indicated programme at the specified start time, channel and duration.

state

string

no

State of the timer

unknown	Timer is an unknown (Error) state
new	Timer is in the process of being created on the server (internal use only)
waiting	Timer is waiting to be retrieved by a TV Recording
sent	Timer has been sent to the TV Recording, but not acknowledged as yet
missing	Timer was not received by a TV Recorder by subsequent ones were
pending	Timer has been acknowledged as scheduled by the TV Recorder
running	Timer is currently being recorded on the TV Recorder
failed	Timer failed to either complete recording or could not be scheduled
completed	Timer successfully completed recording

message

string

no

Human readable message for last action on the timer, e.g. "Scheduled by TV Recorder", "Timer conflict", etc.

series_recording_id

integer

yes

no

Unique identifier for the series recording associated with this timer (See Series Recording)

keyword_id

integer

yes

no

Unique identifier for the keyword associated with this timer (See Keyword)

pre-padding

integer

no

Amount of pre-padding in minutes to be applied to this timer

post-padding

integer

no

Amount of post-padding in minutes to be applied to this timer

padding-type

string

no

Padding type to use for this timer on the TV Recorder

hard	Padding time will always be added to this timer and can cause conflicts with surrounding timers
soft	Padding time will only be added to this timer is there is a tuner available when the recording occurs

Timers (shows/timers)

Get all timers

URL	https://api.icetv.com.au/shows/timers
Method	GET
Query String
Returns	200 OK & Document (XML or JSON)
	401 Unauthorized
	404 Not Found
	503 Service Unavailable

Request

GET https://api.icetv.com.au/shows/timers?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of response

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE shows SYSTEM "http://iceguide.icetv.com.au/iceguide/shows.dtd">
<shows>
	<timer id="15784000841381576705" name="The Simpsons" device_id="23" channel_id="1700" show_id="103458207" start_time="2012-05-09T09:30:00+00:00" duration_minutes="30" action="record" state="waiting" message="Scheduled to record by API" series_recording_id="51" keyword_id="0"/>
	<timer id="15784000841381576706" name="The Simpsons" device_id="23" channel_id="1700" show_id="103585019" start_time="2012-05-16T09:30:00+00:00" duration_minutes="30" action="record" state="waiting" message="Scheduled to record by API" series_recording_id="51" keyword_id="0"/>
	<timer id="15784000841381576707" name="The Simpsons" device_id="23" channel_id="1700" show_id="103679189" start_time="2012-05-23T09:30:00+00:00" duration_minutes="30" action="record" state="waiting" message="Scheduled to record by API" series_recording_id="51" keyword_id="0"/>
</shows>

JSON - Structure of the response

Name	Type	Description
timers	array of timers	Contains all the timers associated with the account

JSON - Example of response

{
	"timers": [
		{
			"action": "record",
			"channel_id": "1700",
			"device_id": "23",
			"duration_minutes": "30",
			"id": "15784000841381576705",
			"keyword_id": "0",
			"message": "Scheduled to record by API",
			"name": "The Simpsons",
			"series_recording_id": "51",
			"show_id": "103458207",
			"start_time": "2012-05-09T09:30:00+00:00",
			"state": "waiting"
		},
		{
			"action": "record",
			"channel_id": "1700",
			"device_id": "23",
			"duration_minutes": "30",
			"id": "15784000841381576706",
			"keyword_id": "0",
			"message": "Scheduled to record by API",
			"name": "The Simpsons",
			"series_recording_id": "51",
			"show_id": "103585019",
			"start_time": "2012-05-16T09:30:00+00:00",
			"state": "waiting"
		},
		{
			"action": "record",
			"channel_id": "1700",
			"device_id": "23",
			"duration_minutes": "30",
			"id": "15784000841381576707",
			"keyword_id": "0",
			"message": "Scheduled to record by API",
			"name": "The Simpsons",
			"series_recording_id": "51",
			"show_id": "103679189",
			"start_time": "2012-05-23T09:30:00+00:00",
			"state": "waiting"
		},
	]
}

Get a specific timer

URL	https://api.icetv.com.au/shows/timers/#
Method	GET
Query String
Returns	200 OK & Document (XML or JSON)
	401 Unauthorized
	404 Not Found
	503 Service Unavailable

Request - URL

GET https://api.icetv.com.au/shows/timers/TIMER_ID&api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of response

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE shows SYSTEM "http://iceguide.icetv.com.au/iceguide/shows.dtd">
<shows>
	<timer id="15784000841381576705" name="The Simpsons" device_id="23" channel_id="1700" show_id="103458207" start_time="2012-05-09T09:30:00+00:00" duration_minutes="30" action="record" state="waiting" message="Scheduled to record by API" series_recording_id="51" keyword_id="0"/>
</shows>

JSON - Structure of the response

Name	Type	Description
timers	array of timers	Contains only the timer requested

JSON - Example of response

{
	"timers": [
		{
			"action": "record",
			"channel_id": "1700",
			"device_id": "23",
			"duration_minutes": "30",
			"id": "15784000841381576705",
			"keyword_id": "0",
			"message": "Scheduled to record by API",
			"name": "The Simpsons",
			"series_recording_id": "51",
			"show_id": "103458207",
			"start_time": "2012-05-09T09:30:00+00:00",
			"state": "waiting"
		}
	]
}

Add a timer

URL	https://api.icetv.com.au/shows/timers/
Method	POST
Query String
Returns	201 Created & Document (XML or JSON)
	401 Unauthorized
	404 Not Found
	406 Not Acceptable
	415 Unsupported Media Type
	503 Service Unavailable

A document containing the new timer record must be sent as part of the request.

The document to be sent to the server omits the "id" and name fields as this is generated by the server.

The server response will include the newly created timer record as it would appear in a single timer GET which allows the caller to update their local cache with the timer id.

Request

POST https://api.icetv.com.au/shows/timers?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of request

<xml version="1.0" encoding="iso-8859-1">
<shows>
	<timer device_id="4250" channel_id="38" show_id="101262483" message="Created by MY APPLICATON NAME" />
</shows>

XML - Example of response

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE shows SYSTEM "http://iceguide.icetv.com.au/iceguide/shows.dtd">
<shows min_hit_minutes="">
  <timer id="15727699466586750978" name="Bob The Builder: Project Build It" device_id="4250" channel_id="38" show_id="101262483" start_time="2011-11-13T03:20:00+00:00" duration_minutes="15" pre-padding="0" post-padding="0" padding-type="" action="record" state="waiting" message="Created by MY APPLICATON NAME" />
</shows>

JSON - Structure of the request

Name	Type	Description	Comment
-	table	The timer's properties	Only "show_id" and "device_id" are mandatory to create the timer, all the other field will get assigned a default value if not specified.

JSON - Example of request

{
	"message" : "Created by MY APPLICATION NAME",
	"channel_id" : "38",
	"show_id" : "101262483",
	"device_id" : "4250"
}

JSON - Structure of the response

Name

Type

Description

Comment

timers

array of timers

Contains the timer just added

The time id can be cached or retrieved later via a get_all_timers

Contains only the timer just added

JSON - Example of response

{
	"timers": [
		{
			"action": "record",
			"channel_id": "38",
			"device_id": "4250",
			"duration_minutes": "30",
			"id": "15784000841381576705",
			"keyword_id": "0",
			"message": "Created by MY APPLICATION NAME",
			"name": "The Simpsons",
			"series_recording_id": "0",
			"show_id": "101262483",
			"start_time": "2012-05-09T09:30:00+00:00",
			"state": "waiting"
		}
	]
}

Modify a timer

URL	https://api.icetv.com.au/shows/timers/#
Method	PUT
Query String
Returns	200 OK
	401 Unauthorized
	404 Not Found
	406 Not Acceptable
	415 Unsupported Media Type
	503 Service Unavailable

The modify timer API can be used to change the details of a timer, including changes of state that occur as part of the timer lifecycle.

Request - URL

PUT https://api.icetv.com.au/shows/timers/TIMER_ID?api_key=API_KEY&application_version=APPLICATION_VERSION&email_address=EMAIL_ADDRESS&token=TOKEN

XML - Example of request

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE shows SYSTEM "http://iceguide.icetv.com.au/iceguide/shows.dtd">
<shows>
	<timer id="15727699466586750978" device_id="4250" channel_id="38" show_id="101262483" action="record" state="running" message="Recording started on MY TV RECORDER NAME" />
</shows>

XML - Example of response

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE shows SYSTEM "http://iceguide.icetv.com.au/iceguide/shows.dtd">
<shows>
	<timer id="15727699466586750978" name="Bob The Builder: Project Build It" device_id="4250" channel_id="38" show_id="101262483" start_time="2011-11-13T03:20:00+00:00" duration_minutes="15" pre-padding="0" post-padding="0" paddingtype="" action="record" state="running" message="Recording started on MY TV RECORDER NAME" />
</shows>

NOTE: A timer can be modified by sending 2 types of JSON document, a single object or an array of timer containing the timer information you want to modify. To know what field can be modified please refer to the Read-only column of Timer.

JSON - Structure of the request - array

Name

Type

Description

Comment

timers

timer array

Contains the fields of the timer you want to change

Fields that aren't specified will keep their value.

The array has to contain only one timer as only one timer can be modified at a time

JSON - Structure of the request - single object

Name	Type	Description	Comment
	timer object	Contains the fields of the timer you want to change	Fields that aren't specified will keep their value.

JSON - Example of request - array

{
	"timers" : [
		{
			"state" : "running",
			"message" : "Recording started on MY TV RECORDER NAME",
			"action" : "record",
			"show_id" : "104319906",
			"device_id" : "23"
		}
	]
}

JSON - example of request - single object

{
	"state" : "running",
	"message" : "Recording started on MY TV RECORDER NAME",
	"action" : "record",
	"show_id" : "104319906",
	"device_id" : "23"
}

JSON - Structure of the response

Name	Type	Description
timers	array of timers	Contains the timer just modified

JSON - Example of response

{
	"timers" : [
		{
			"id" : "15792720048868818945",
			"state" : "running",
			"series_recording_id" : "9",
			"message" : "Recording started on MY TV RECORDER NAME",
			"start_time" : "2012-07-05T13:30:00+00:00",
			"keyword_id" : "0",
			"action" : "record",
			"channel_id" : "2453",
			"show_id" : "104319906",
			"device_id" : "23",
			"duration_minutes" : "30",
			"name" : "PI: Paranormal Investigators"
		}
	]
}

Delete a timer

URL	https://api.icetv.com.au/shows/timers/#
Method	DELETE
Query String
Returns	200 OK
	401 Unauthorized
	405 Method Not Allowed
	503 Service Unavailable

Request

DELETE https://api.icetv.com.au/shows/timers/15727699466586750978?api_key=API_KEY&application_version&email_address=EMAIL_ADDRESS&token=TOKEN