Skip to content

Latest commit

 

History

History
397 lines (354 loc) · 14 KB

streams.md

File metadata and controls

397 lines (354 loc) · 14 KB
Raw

Streams

Streams are video broadcasts that are currently live. They have a broadcaster and are part of a channel.

Endpoint Description
GET /streams/:channel/ Get stream object
GET /streams Get stream object
GET /streams/featured Get a list of featured streams
GET /streams/summary Get a summary of streams
GET /streams/followed Get a list of streams user is following

GET /streams/:channel/

Returns a stream object if live.

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' \
-X GET https://api.twitch.tv/kraken/streams/test_channel

Example Response

If offline

{
  "stream": null,
  "_links": {
    "self": "https://api.twitch.tv/kraken/streams/test_channel",
    "channel": "https://api.twitch.tv/kraken/channels/test_channel"
  }
}

If online

{
  "_links": {
    "channel": "https://api.twitch.tv/kraken/channels/test_channel",
    "self": "https://api.twitch.tv/kraken/streams/test_channel"
  },
  "stream": {
    "game": "StarCraft II: Heart of the Swarm",
    "viewers": 2123,
    "average_fps": 29.9880749574,
    "video_height": 720,
    "created_at": "2015-02-12T04:42:31Z",
    "_id": 4989654544,
    "channel": {
      "mature": false,
      "status": "test status",
      "broadcaster_language": "en",
      "display_name": "test_channel",
      "game": "StarCraft II: Heart of the Swarm",
      "delay": 0,
      "language": "en",
      "_id": 12345,
      "name": "test_channel",
      "created_at": "2007-05-22T10:39:54Z",
      "updated_at": "2015-02-12T04:15:49Z",
      "logo": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_image-94a42b3a13c31c02-300x300.jpeg",
      "banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_header_image-08dd874c17f39837-640x125.png",
      "video_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_offline_image-b314c834d210dc1a-640x360.png",
      "background": null,
      "profile_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_banner-6936c61353e4aeed-480.png",
      "profile_banner_background_color": "null",
      "partner": true,
      "url": "http://www.twitch.tv/test_channel",
      "views": 49144894,
      "followers": 215780,
      "_links": {
        "self": "https://api.twitch.tv/kraken/channels/test_channel",
        "follows": "https://api.twitch.tv/kraken/channels/test_channel/follows",
        "commercial": "https://api.twitch.tv/kraken/channels/test_channel/commercial",
        "stream_key": "https://api.twitch.tv/kraken/channels/test_channel/stream_key",
        "chat": "https://api.twitch.tv/kraken/chat/test_channel",
        "features": "https://api.twitch.tv/kraken/channels/test_channel/features",
        "subscriptions": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions",
        "editors": "https://api.twitch.tv/kraken/channels/test_channel/editors",
        "teams": "https://api.twitch.tv/kraken/channels/test_channel/teams",
        "videos": "https://api.twitch.tv/kraken/channels/test_channel/videos"
      }
    },
    "preview": {
      "small": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-80x45.jpg",
      "medium": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-320x180.jpg",
      "large": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-640x360.jpg",
      "template": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-{width}x{height}.jpg"
    },
    "_links": {
      "self": "https://api.twitch.tv/kraken/streams/test_channel"
    }
  }
}

GET /streams

Returns a list of stream objects that are queried by a number of parameters sorted by number of viewers descending.

Parameters

Name Required? Type Description
game optional string Streams categorized under game.
channel optional string Streams from a comma separated list of channels.
limit optional integer Maximum number of objects in array. Default is 25. Maximum is 100.
offset optional integer Object offset for pagination. Default is 0.
client_id optional string Only shows streams from applications of client_id.

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' \
-X GET https://api.twitch.tv/kraken/streams?game=StarCraft+II%3A+Heart+of+the+Swarm&channel=test_channel,test_channel2

Example Response

{
  "_total": 12345,
  "streams": [
    {
      "game": "StarCraft II: Heart of the Swarm",
      "viewers": 2123,
      "average_fps": 29.9880749574,
      "video_height": 720,
      "created_at": "2015-02-12T04:42:31Z",
      "_id": 4989654544,
      "channel": {
        "mature": false,
        "status": "test status",
        "broadcaster_language": "en",
        "display_name": "test_channel",
        "game": "StarCraft II: Heart of the Swarm",
        "delay": 0,
        "language": "en",
        "_id": 12345,
        "name": "test_channel",
        "created_at": "2007-05-22T10:39:54Z",
        "updated_at": "2015-02-12T04:15:49Z",
        "logo": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_image-94a42b3a13c31c02-300x300.jpeg",
        "banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_header_image-08dd874c17f39837-640x125.png",
        "video_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_offline_image-b314c834d210dc1a-640x360.png",
        "background": null,
        "profile_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_banner-6936c61353e4aeed-480.png",
        "profile_banner_background_color": "null",
        "partner": true,
        "url": "http://www.twitch.tv/test_channel",
        "views": 49144894,
        "followers": 215780,
        "_links": {
          "self": "https://api.twitch.tv/kraken/channels/test_channel",
          "follows": "https://api.twitch.tv/kraken/channels/test_channel/follows",
          "commercial": "https://api.twitch.tv/kraken/channels/test_channel/commercial",
          "stream_key": "https://api.twitch.tv/kraken/channels/test_channel/stream_key",
          "chat": "https://api.twitch.tv/kraken/chat/test_channel",
          "features": "https://api.twitch.tv/kraken/channels/test_channel/features",
          "subscriptions": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions",
          "editors": "https://api.twitch.tv/kraken/channels/test_channel/editors",
          "teams": "https://api.twitch.tv/kraken/channels/test_channel/teams",
          "videos": "https://api.twitch.tv/kraken/channels/test_channel/videos"
        }
      },
      "preview": {
        "small": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-80x45.jpg",
        "medium": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-320x180.jpg",
        "large": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-640x360.jpg",
        "template": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-{width}x{height}.jpg"
      },
      "_links": {
        "self": "https://api.twitch.tv/kraken/streams/test_channel"
      }
    },
    ...
  ],
  "_links": {
    "summary": "https://api.twitch.tv/kraken/streams/summary",
    "followed": "https://api.twitch.tv/kraken/streams/followed",
    "next": "https://api.twitch.tv/kraken/streams?channel=test_channel%2Ctest_channel2&game=StarCraft+II%3A+Heart+of+the+Swarm&limit=100&offset=100",
    "featured": "https://api.twitch.tv/kraken/streams/featured",
    "self": "https://api.twitch.tv/kraken/streams?channel=test_channel%2Ctest_channel2&game=StarCraft+II%3A+Heart+of+the+Swarm&limit=100&offset=0"
  }
}

GET /streams/featured

Returns a list of featured (promoted) stream objects.

Parameters

Name Required? Type Description
limit optional integer Maximum number of objects in array. Default is 25. Maximum is 100.
offset optional integer Object offset for pagination. Default is 0.

Note that the number of promoted streams varies from day to day, and there is no guarantee on how many streams will be promoted at a given time.

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' \
-X GET https://api.twitch.tv/kraken/streams/featured

Example Response

{
  "_links": {
     "self": "https://api.twitch.tv/kraken/streams/featured?limit=25&offset=0",
     "next": "https://api.twitch.tv/kraken/streams/featured?limit=25&offset=25"
  },
  "featured": [
    {
      "image": "http://s.jtvnw.net/jtv_user_pictures/hosted_images/TwitchPartnerSpotlight.png",
      "text": "<p>some html to describe this featured stream</p>",
      "title": "Twitch Partner Spotlight",
      "sponsored": false,
      "scheduled": true,
      "stream": {
        "game": "StarCraft II: Heart of the Swarm",
        "viewers": 2123,
        "average_fps": 29.9880749574,
        "video_height": 720,
        "created_at": "2015-02-12T04:42:31Z",
        "_id": 4989654544,
        "channel": {
          "mature": false,
          "status": "test status",
          "broadcaster_language": "en",
          "display_name": "test_channel",
          "game": "StarCraft II: Heart of the Swarm",
          "delay": 0,
          "language": "en",
          "_id": 12345,
          "name": "test_channel",
          "created_at": "2007-05-22T10:39:54Z",
          "updated_at": "2015-02-12T04:15:49Z",
          "logo": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_image-94a42b3a13c31c02-300x300.jpeg",
          "banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_header_image-08dd874c17f39837-640x125.png",
          "video_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-channel_offline_image-b314c834d210dc1a-640x360.png",
          "background": null,
          "profile_banner": "http://static-cdn.jtvnw.net/jtv_user_pictures/test_channel-profile_banner-6936c61353e4aeed-480.png",
          "profile_banner_background_color": "null",
          "partner": true,
          "url": "http://www.twitch.tv/test_channel",
          "views": 49144894,
          "followers": 215780,
          "_links": {
            "self": "https://api.twitch.tv/kraken/channels/test_channel",
            "follows": "https://api.twitch.tv/kraken/channels/test_channel/follows",
            "commercial": "https://api.twitch.tv/kraken/channels/test_channel/commercial",
            "stream_key": "https://api.twitch.tv/kraken/channels/test_channel/stream_key",
            "chat": "https://api.twitch.tv/kraken/chat/test_channel",
            "features": "https://api.twitch.tv/kraken/channels/test_channel/features",
            "subscriptions": "https://api.twitch.tv/kraken/channels/test_channel/subscriptions",
            "editors": "https://api.twitch.tv/kraken/channels/test_channel/editors",
            "teams": "https://api.twitch.tv/kraken/channels/test_channel/teams",
            "videos": "https://api.twitch.tv/kraken/channels/test_channel/videos"
          }
        },
        "preview": {
          "small": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-80x45.jpg",
          "medium": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-320x180.jpg",
          "large": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-640x360.jpg",
          "template": "http://static-cdn.jtvnw.net/previews-ttv/live_user_test_channel-{width}x{height}.jpg"
        },
        "_links": {
          "self": "https://api.twitch.tv/kraken/streams/test_channel"
        }
      }
    },
    [...]
  ]
}

GET /streams/summary

Returns a summary of current streams.

Parameters

Name Required? Type Description
game optional string Only show stats for the set game

Example Request

curl -H 'Accept: application/vnd.twitchtv.v3+json' \
-X GET https://api.twitch.tv/kraken/streams/summary

Example Response

{
  "viewers": 194774,
  "_links": {
    "self": "https://api.twitch.tv/kraken/streams/summary"
  },
  "channels": 4144
}

GET /streams/followed

See the Users resource

Embedding

See here for embedding.