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
   },
   ...
   ]
}