Contents

Search Reference

While you can migrate from v3 to v5, know that v5 is deprecated and will be shutdown in the future. We prefer that you migrated directly to the new Twitch API.

Endpoint Description
Search Channels

Searches for channels based on a specified query parameter. A channel is returned if the query parameter is matched entirely or partially, in the channel description or game name.

Search Games

Searches for games based on a specified query parameter. A game is returned if the query parameter is matched entirely or partially, in the game name.

Search Streams

Searches for streams based on a specified query parameter. A stream is returned if the query parameter is matched entirely or partially, in the channel description or game name.

Search Channels

Searches for channels based on a specified query parameter. A channel is returned if the query parameter is matched entirely or partially, in the channel description or game name.

Authentication

None

URL

GET https://api.twitch.tv/kraken/search/channels?query=<URL encoded search query>

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return, sorted by number of followers. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.

Example Request

This gets the 25 most followed channels that have “starcraft” associated with them.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/search/channels?query=starcraft'

Example Response

{
   "_total": 2147,
   "channels": [{
      "_id": 42508152,
      "broadcaster_language": "en",
      "created_at": "2013-04-15T20:39:45.364539Z",
      "display_name": "StarCraft",
      "followers": 149012,
      "game": "StarCraft II",
      "language": "en",
      "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/starcraft-profile_image-91cdefae9d5ee8b4-300x300.png",
      "mature": false,
      "name": "starcraft",
      "partner": false,
      "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/starcraft-profile_banner-8a0bd21175f60469-480.png",
      "profile_banner_background_color": "",
      "status": "2016 WCS Global Finals @BlizzCon",
      "updated_at": "2016-12-15T21:35:27.851329Z",
      "url": "https://www.twitch.tv/starcraft",
      "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/starcraft-channel_offline_image-9f80ccdb7362a1d9-1920x1080.jpeg",
      "views": 19881024
   },
   ...
   ]
}

Search Games

Searches for games based on a specified query parameter. A game is returned if the query parameter is matched entirely or partially, in the game name.

Authentication

None

URL

GET https://api.twitch.tv/kraken/search/games?query=<URL encoded search query>

Optional Query String Parameter

Name Type Description
live boolean If true, returns only games that are live on at least one channel. Default: false.

Example Request

This searches for games that have “star” associated with them.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/search/games?query=star'

Example Response

{
   "games": [{
      "_id": 490422,
      "box": {
            "large": "https://static-cdn.jtvnw.net/ttv-boxart/StarCraft%20II-272x380.jpg",
            "medium": "https://static-cdn.jtvnw.net/ttv-boxart/StarCraft%20II-136x190.jpg",
            "small": "https://static-cdn.jtvnw.net/ttv-boxart/StarCraft%20II-52x72.jpg",
            "template": "https://static-cdn.jtvnw.net/ttv-boxart/StarCraft%20II-{width}x{height}.jpg"
      },
      "giantbomb_id": 0,
      "logo": {
            "large": "https://static-cdn.jtvnw.net/ttv-logoart/StarCraft%20II-240x144.jpg",
            "medium": "https://static-cdn.jtvnw.net/ttv-logoart/StarCraft%20II-120x72.jpg",
            "small": "https://static-cdn.jtvnw.net/ttv-logoart/StarCraft%20II-60x36.jpg",
            "template": "https://static-cdn.jtvnw.net/ttv-logoart/StarCraft%20II-{width}x{height}.jpg"
      },
      "name": "StarCraft II",
      "popularity": 5051
   },
   ...
   ]
}

Search Streams

Searches for streams based on a specified query parameter. A stream is returned if the query parameter is matched entirely or partially, in the channel description or game name.

Authentication

None

URL

GET https://api.twitch.tv/kraken/search/streams?query=<URL encoded search query>

Optional Query String Parameters

Name Type Description
limit integer Maximum number of objects to return, sorted by number of current viewers. Default: 25. Maximum: 100.
offset integer Object offset for pagination of results. Default: 0.
hls boolean If true, returns only HLS streams; if false, only RTMP streams; if not set, both HLS and RTMP streams. HLS is HTTP Live Streaming, a live-streaming communications protocol. RTMP is Real-Time Media Protocol, an industry standard for moving video around a network. Default: not set.

Example Request

This gets the 25 streams with the most current viewers that have “starcraft” associated with them.

curl -H 'Accept: application/vnd.twitchtv.v5+json' \
-H 'Client-ID: uo6dggojyb8d6soh92zknwmi5ej1q2' \
-X GET 'https://api.twitch.tv/kraken/search/streams?query=starcraft'

Example Response

{
   "_total": 115,
   "streams": [{
      "_id": 23937913552,
      "average_fps": 60.7418471496,
      "channel": {
            "_id": 71852806,
            "broadcaster_language": "fr",
            "created_at": "2014-09-24T15:06:58.315907Z",
            "display_name": "OgamingSC2",
            "followers": 43904,
            "game": "StarCraft II",
            "language": "fr",
            "logo": "https://static-cdn.jtvnw.net/jtv_user_pictures/ogamingsc2-profile_image-9021dccf9399929e-300x300.jpeg",
            "mature": false,
            "name": "ogamingsc2",
            "partner": false,
            "profile_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/ogamingsc2-profile_banner-d418aed2c0ef7d35-480.jpeg",
            "profile_banner_background_color": "",
            "status": "IEM Season XI - Gyeonggi - Maru vs Stats",
            "updated_at": "2016-12-15T21:35:13.075296Z",
            "url": "https://www.twitch.tv/ogamingsc2",
            "video_banner": "https://static-cdn.jtvnw.net/jtv_user_pictures/ogamingsc2-channel_offline_image-1570cf4930177aa3-1920x1080.jpeg",
            "views": 22280087
      },
      "created_at": "2016-12-15T16:23:57Z",
      "delay": 0,
      "game": "StarCraft II",
      "is_playlist": false,
      "preview": {
            "large": "https://static-cdn.jtvnw.net/previews-ttv/live_user_ogamingsc2-640x360.jpg",
            "medium": "https://static-cdn.jtvnw.net/previews-ttv/live_user_ogamingsc2-320x180.jpg",
            "small": "https://static-cdn.jtvnw.net/previews-ttv/live_user_ogamingsc2-80x45.jpg",
            "template": "https://static-cdn.jtvnw.net/previews-ttv/live_user_ogamingsc2-{width}x{height}.jpg"
      },
      "video_height": 720,
      "viewers": 761
   },
   ...
   ]
}
+