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