A live-streaming event is an event that is broadcast on YouTube as it occurs. The API uses the following feeds and entries to return information about live-streaming events:

An event feed contains a list of live-streaming events created by a specific user. An event feed comprises a series of event entries.
An event entry contains metadata about a single live-streaming event, such as the event's name, description, start time, and status. An event entry is currently associated with a single live video entry; however, a single event may eventually be associated with multiple live video entries.
A live video entry contains information about a live video stream of an event. A live video entry is an extension of the video entry, which is used in other types of video feeds, including search feeds, uploads, and so forth. A live video entry may also contain additional tags that would be used to convey information about a live video stream but that would not be relevant to other videos, such as information about the content delivery network used to stream the content.

If a video entry refers to a live video, the entry will contain a <category> tag with a scheme attribute value of http://schemas.google.com/g/2005#kind and aterm attribute value of http://gdata.youtube.com/schemas/2007#liveVideo.

The following sections explain different options for retrieving live-streaming events:

Live event charts

You can retrieve several different standard feeds, or charts, listing live events on YouTube.

To retrieve a live event chart, send a GET request to the URL associated with that chart. Note that you must be using version 2 of the YouTube API to retrieve any of these charts. You can specify the API version using either the v parameter or the GData-Version HTTP request header.

The following table describes the charts that you can retrieve and identifies the URL associated with each chart:

Chart name	Feed ID	URL and Description
Featured live events	featured	URL: https://gdata.youtube.com/feeds/api/charts/live/events/featured Description: This feed lists promoted live events that are currently happening or will soon take place.
Current live events	live_now	URL: https://gdata.youtube.com/feeds/api/charts/live/events/live_now Description: This feed lists live events that are currently active.
Upcoming live events	upcoming	URL: https://gdata.youtube.com/feeds/api/charts/live/events/upcoming Description: This feed lists events that will take place within the time frame specified for the `time` parameter. Valid parameter values are `today` (one day), `this_week` (seven days), `this_month` (one month), and `all_time`, and `all_time` is the default value.
Recently broadcast	recently_broadcasted	URL: https://gdata.youtube.com/feeds/api/charts/live/events/recently_broadcasted Description: This feed lists events that recently ended.

API requests to retrieve live event charts can specify any of the following parameters:

The region parameter filters a chart to only include live events that are featured within the specified region.

Retrieving a user's events feed

This section explains how to retrieve a feed listing a specific user's live-streaming events. Note that YouTube has not enabled all user accounts to create and stream live events. If a user has not created any live-streaming events or is not allowed to create live-streaming events, that user's events feed will not contain any entries.

To request a feed of the currently logged-in user's live-streaming events, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
```
https://gdata.youtube.com/feeds/api/users/default/live/events?v=2
```
To request a feed of another user's live-streaming events, send an HTTP GET request to the following URL. Note that this request does not require authentication.
```
https://gdata.youtube.com/feeds/api/users/userId/live/events?v=2
```
In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

Determining whether a user can create live events

If a user can create live events, then the user's profile entry will contain a <gd:feedLink> that points to the user's events feed. The tag will have the following attributes:

The rel attribute value will be http://gdata.youtube.com/schemas/2007#user.live.
The href attribute value will specify the URL of the user's events feed.
The countHint attribute value will specify the number of events in the feed.

The XML below shows a sample <gd:feedLink> tag:

<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.live'
    href='https://gdata.youtube.com/feeds/api/users/userId/live/events?v=2'
    countHint='11'/>

Special query parameters for retrieving live events

YouTube supports the following API query parameters specifically for requests to retrieve live event feeds:

status – The API response will only include events that are either pending (not yet started), active (in progress), completed, cancelled, or rejected.
starts-before – The API response will only include events that started before (or will start before) the given date and time.
starts-after – The API response will only include events that started after (or will start after) the given date and time.
ends-before – The API response will only include events that ended before (or will end before) the given date and time.
ends-after – The API response will only include events that ended after (or will end after) the given date and time.

In addition, you can use the inline parameter to indicate that each entry in a live events feed should, in turn, contain an entry that points to the actual video content associated with the event. For example, the live event entry could contain a video entry if there is a single video stream associated with the event, or it could contain a playlist entry if there are multiple videos associated with the event.

If you set the inline parameter to true, the <content> tag in each event feed entry will encapsulate a video or playlist entry containing details about the video(s) associated with the event.
If you do not set the inline parameter or you set the parameter's value to false, the <content> tag in each event feed entry will contain a src attribute that points to the URL you would use to retrieve information about the video.

If you do set the inline parameter to true, you may find it helpful to use the partial response feature to limit the size of the API response.

Sample live events feed

The following API request retrieves the live events for the YouTube user ytatestuser. Since the inline parameter is set to true, each entry's <content> tag will encapsulate the video entry associated with the event.

https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?v=2&inline=true

The following XML shows the API response for this request. The feed contains a series of <entry> tags, with each entry describing a live event. Each entry contains the title, description, author, date, and status of an event, among other fields. (Note that only the first entry is displayed below.)

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/&quot;CEMDSHwyeCp7ImA9WhZWF0s.&quot;'>
  <id>tag:youtube.com,2008:user:ytatestuser:live:events</id>
  <updated>2011-05-18T23:47:59.290Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#liveEvent'/>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/batch'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?start-index=1&max-results=25'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?alt=atom-service'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>4</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>

  <entry
      gd:etag='W/&quot;C08MR347eCp7ImA9WhZWGUk.&quot;'>
    <id>tag:youtube.com,2008:live:event:ABF128AfLamNfZYVMiky</id>
    <published>2011-05-03T17:44:47.000Z</published>
    <updated>2011-05-21T01:38:06.000Z</updated>
    <app:edited>2011-05-21T01:38:06.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#liveEvent'/>
    <title>Test Event</title>
    <summary>Testing live streaming.</summary>
    <content type='application/atom+xml'>

      <entry
          gd:etag='W/&quot;DkEMRn47eCp7ImA9WhZXFEk.&quot;'>
        <id>tag:youtube.com,2008:video:BM7FWtADD0s</id>
        <published>2011-05-03T17:44:47.000Z</published>
        <updated>2011-05-03T17:44:47.000Z</updated>
        <app:edited>2011-05-03T17:44:47.000Z</app:edited>
        <app:control>
          <app:draft>yes</app:draft>
          <yt:state name='processing'/>
        </app:control>
        <category scheme='http://schemas.google.com/g/2005#kind'
            term='http://gdata.youtube.com/schemas/2007#video'/>
        <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
            term='Entertainment' label='Entertainment'/>
        <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
            term='match'/>
        <title>Test Event</title>
        <link rel='alternate' type='text/html'
            href='https://www.youtube.com/watch?v=BM7FWtADD0s&feature=youtube_gdata'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/responses?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/ratings?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/complaints?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/related?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.captionTracks' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/captions?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#insight.views'
            type='text/html'
            href='http://insight.youtube.com/video-analytics/csvreports?query=...'/>
        <author>
          <name>ytatestuser</name>
          <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
          <yt:userId>LKtfV8Wl406AI76bebMmnA</yt:userId>
        </author>
        <yt:accessControl action='comment' permission='allowed'/>
        <yt:accessControl action='commentVote' permission='allowed'/>
        <yt:accessControl action='videoRespond' permission='moderated'/>
        <yt:accessControl action='rate' permission='allowed'/>
        <yt:accessControl action='embed' permission='allowed'/>
        <yt:accessControl action='list' permission='allowed'/>
        <yt:accessControl action='syndicate' permission='allowed'/>
        <gd:comments>
          <gd:feedLink href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/comments?v=2'
              countHint='0'/>
        </gd:comments>
        <media:group>
          <media:category label='Entertainment'
            scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Entertainment</media:category>
          <media:content url='http://www.youtube.com/v/BM7FWtADD0s?f=videos&app=youtube_gdata'
              type='application/x-shockwave-flash' medium='video' isDefault='true'
              expression='full' duration='0' yt:format='5'/>
          <media:credit role='uploader' scheme='urn:youtube'
              yt:display='ytatestuser'>ytatestuser</media:credit>
          <media:description type='plain'>Testing live streaming.</media:description>
          <media:keywords>testing</media:keywords>
          <media:player url='https://www.youtube.com/watch?v=BM7FWtADD0s&feature=youtube_gdata_player'/>
          <media:restriction type='country'
              relationship='deny'>FR DE SE</media:restriction>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/default.jpg'
              height='90' width='120' time='00:00:00' yt:name='default'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/hqdefault.jpg'
              height='360' width='480' yt:name='hqdefault'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/mqdefault.jpg'
              height='180' width='320' yt:name='mqdefault'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/1.jpg'
              height='90' width='120' time='00:00:00' yt:name='start'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/2.jpg'
              height='90' width='120' time='00:00:00' yt:name='middle'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/3.jpg'
              height='90' width='120' time='00:00:00' yt:name='end'/>
          <media:title type='plain'>Test Event</media:title>
          <yt:duration seconds='0'/>
          <yt:uploaded>2011-05-03T17:44:47.000Z</yt:uploaded>
          <yt:videoid>BM7FWtADD0s</yt:videoid>
        </media:group>
      </entry>

    </content>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
        type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/videos/values%3A+%22$2BM7FWtADD0s?v=2'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLamNfZYVMiky'/>
    <link rel='edit' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLamNfZYVMiky'/>
    <author>
      <name>ytatestuser</name>
      <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
      <yt:userId>LKtfV8Wl406AI76bebMmnA</yt:userId>
    </author>
    <media:group>
      <media:description type='plain'>Testing live streaming.</media:description>
      <media:title type='plain'>Test Event</media:title>
    </media:group>
    <yt:status>pending</yt:status>
    <yt:when start='2011-06-24T00:00:00.000Z'/>
  </entry>

</feed>

Retrieving a single live event

There are two ways to obtain the API URL from which you would request information about a single live event:

In an event feed entry, the <link> tag that has a rel attribute value of self specifies the URL from which you would retrieve that same entry via the API. When retrieving a live event entry, you can use the inline parameter in the same way that you would use it when requesting a live events feed.
If a video entry contains a <link> tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#live.event, then the video is associated with a live event. The tag's href attribute value will specify the API URL that you would use to retrieve information about the event itself.

https://developers.google.com/youtube/2.0/developers_guide_protocol_retrieving_live_events

SIVANANDA REDDY GANGIREDDY

Pages

Saturday, June 2, 2012

YouTube API v2.0 - Retrieving Live Events