Search

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.

1
2
3
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
   "_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.

1
2
3
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
   "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.

1
2
3
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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
   "_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
   },
   ...
   ]
}