Search Reference

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