Abelson Info TV Guide Feed V2

Introduction

The TV Guide feed provides details of broadcasts for sporting events.

In order to track changes to broadcasts as they occur, you should use the updates feed, which is described below.

The updates feed contains links to the broadcasts feed, which is where you'll find all the available information relevant to a particular broadcast.

Feed Format

Data is provided in XML format and delivered via HTTP. Clients consume the feed by making HTTP GET requests to Abelson Info's server.

Wherever a time value is provided - for example an event's start time, or the time at which an event was last update - it will be given in ISO 8601 format.

Feed IDs

The IDs for broadcasts, events, competitions, sports and regions are unique throughout the system for the given entity type.

Access Restriction

Access to the feed is restricted by token, which will be assigned to you by Abelson Info. Please contact engineering@abelsoninfo.com to arrange for this.

Overview

Regions

The regions currently supported by the TV Guide feed are:

The Updates Feed

The updates feed lists broadcasts which have been created, updated or deleted or have had their parent event updated or deleted, in chronological order. This means a broadcast will appear in the feed if, for example, the name of the event has changed even though the broadcast data (start and end times) has not changed. It excludes broadcasts that took place in the past.

You can poll the updates feeds at a regular interval, to ensure that the latency between an update occurring, and it being detected by your client application, is minimal. By using the updates feed you will also eliminate the overhead of requesting and parsing data unnecessarily, because your application will only request data when a change has occurred.

When using the updates feeds, you need to provide a since query parameter to specify the point from which you would like to view changes.

The since parameter should be in ISO 8601 format. This is the same format used by the updated_at attribute of each update element within the updates feed.

Only a limited number of records are returned for each request made, so your application will need to be able to page through the feed using the since parameter. To do this, follow these steps:

• Issue your first HTTP request to the updates feed either omitting the since parameter or specifying an arbitrary time from which you wish to view updates.
• Use the URLs provided by the href attribute of each update element to request updated data for each event listed.
• The type attribute indicates the type of update. A new or modified broadcast will have a value of update, a deleted broadcast will have the value of delete.
• Capture the value of the updated_at attribute of the last update element.
• On the subsequent request to the updates feed, use that updated_at value as the value of the since parameter.
• Continue using the updates feed to request event data until you receive a response from the updates feed which contains no update or delete elements.
• You'll then need to continue to poll the updates feed at a regular interval, using the same since parameter, if you wish to receive live data.

Please note: It's important that you don't omit the fractional seconds component of the since value. This ensures that your application will not attempt to continually page through the same data should a large number of updates be made within a short period of time.

Updates Feed Example XML

 <?xml version="1.0" encoding="UTF-8"?>
 <broadcast-updates generated_at="2010-05-20T11:48:42.969179Z">
   <broadcast type="update" updated_at="2010-05-17T10:09:37.155739Z" href="/v2/TOKEN/broadcast/123060.xml"/>
   <broadcast type="update" updated_at="2010-05-17T10:09:53.253653Z" href="/v2/TOKEN/broadcast/123062.xml"/>
   <broadcast type="update" updated_at="2010-05-17T10:35:55.678559Z" href="/v2/TOKEN/broadcast/123114.xml"/>
   <broadcast type="delete" updated_at="2010-05-17T10:49:13.947337Z" href="/v2/TOKEN/broadcast/123145.xml"/>
   <broadcast type="update" updated_at="2010-05-17T10:52:46.195929Z" href="/v2/TOKEN/broadcast/123158.xml"/>
 </broadcast-updates>

The Broadcast Feed

Please note: Several elements (event, competition, sport and competitor) have a uid attribute. This attribute is the unique id for the event, sport etc across all Abelson Info systems. Not just within the TV Guide feed. The value can be blank.

Broadcast Feed Example XML

 <?xml version="1.0" encoding="UTF-8"?>
 <broadcast type="update" id="200978" updated_at="2011-02-16T11:22:50.492892Z">
   <channel id="191">
     <name>ESPN America</name>
     <regions>
       <region id="8">UK</region>
     </regions>
   </channel>
   <start_time>2011-02-17T00:00:00.0Z</start_time>
   <end_time>2011-02-17T02:30:00.0Z</end_time>
   <event type="update" uid="basketball/event/78236" id="63798" updated_at="2011-02-16T11:22:50.625802Z">
     <name>Duke Blue Devils at Virginia Cavaliers</name>
     <competition uid="basketball/competition/71" id="15">NCAAB</competition>
     <sport uid="basketball" id="4">Basketball</sport>
     <start_time>2011-02-17T00:00:00.0Z</start_time>
     <end_time>2011-02-17T02:30:00.0Z</end_time>
     <competitors>
       <competitor name="Duke Blue Devils" uid="basketball/team/5425"/>
       <competitor name="Virginia Cavaliers" uid="basketball/team/6715"/>
     </competitors>
   </event>
 </broadcast>

The Channels Feed

Schedule as broadcasts

The schedule as broadcasts feed lists all the broadcasts on the given day that the user has access to. Broadcasts that start before the given date but are running during the date given are included. As are broadcasts that start on the given date but run into the next. This means calls to the schedule for subsequent days can include the same broadcast.

Please note: Deleted broadcasts are included.

The XML is identical to the broadcast XML above, just held between a broadcasts element

Schedule as broadcasts example xml

  <?xml version="1.0" encoding="UTF-8"?>
  <broadcasts>
    <broadcast type="update" updated_at="2015-07-14T17:07:15.342236+01:00" id="909235">
      <channel id="6">
        <name>ATR</name>
        <regions>
          <region id="2">Ireland</region>
          <region id="7">United Kingdom</region>
          <region id="35">United Kingdom</region>
          <region id="8">UK</region>
          <region id="10">Ireland</region>
        </regions>
      </channel>
      <start_time>2015-07-14T21:15:00.0+01:00</start_time>
      <end_time>2015-07-15T01:15:00.0+01:00</end_time>
      <event type="update" updated_at="2015-07-14T17:07:15.342236+01:00" uid="" id="269921">
        <name>Fort Erie </name>
        <competition uid="" id="80">US Racing</competition>
        <sport uid="" id="13">Horse Racing</sport>
        <start_time>2015-07-14T21:15:00.0+01:00</start_time>
        <end_time>2015-07-15T01:15:00.0+01:00</end_time>
      </event>
    </broadcast>

    <!-- more broadcasts -->
  </broadcasts>