Tracking Viewer Ratings of Twitch Stream Minute-by-Minute

This blog post shows how to use the Twitch API to retrieve the current number of viewers of a channel. See this page for an application example.

Get your API key

Although you can use the API without key, using the client_id is recommended to make sure you are to rate limited by Twitch. You can get the client_id by going to and registering a new application:


The client ID will automatically be generated for you:


Calling the API response

You call the API with requests to<CHANNEL>?client_id=<YOUR_CLIENT_ID>

For example, to get the information for channel manvsgame and client_id abcdef1234567890 you would request:

If the channel is offline, the response will look like that:

{u'_links': {u'channel': u'',
             u'self': u''},
 u'stream': None}

If the channel is online, the response will look like that:

{u'_links': {u'channel': u'',
             u'self': u''},
 u'stream': {u'_id': 7797659104L,
             u'_links': {u'self': u''},
             u'channel': {u'_id': 8330235,
                          u'_links': {u'chat': u'',
                                      u'commercial': u'',
                                      u'editors': u'',
                                      u'features': u'',
                                      u'follows': u'',
                                      u'self': u'',
                                      u'stream_key': u'',
                                      u'subscriptions': u'',
                                      u'teams': u'',
                                      u'videos': u''},
                          u'abuse_reported': None,
                          u'background': u'',
                          u'banner': None,
                          u'created_at': u'2009-09-17T19:42:52Z',
                          u'delay': 0,
                          u'display_name': u'MANvsGAME',
                          u'game': u'I Wanna Be The Guy',
                          u'logo': u'',
                          u'mature': True,
                          u'name': u'manvsgame',
                          u'profile_banner': u'',
                          u'profile_banner_background_color': None,
                          u'status': u'MAN vs I WANNA BE THE GUY - I Wanna Be The Month!',
                          u'updated_at': u'2013-12-10T08:06:53Z',
                          u'url': u'',
                          u'video_banner': u'',
                          u'views': 26903371},
             u'game': u'I Wanna Be The Guy',
             u'preview': {u'large': u'',
                          u'medium': u'',
                          u'small': u'',
                          u'template': u'{width}x{height}.jpg'},
             u'viewers': 9233}}

The number of viewers is in ‘stream’ -> ‘viewers’ (e.g. 9233).

Example code

The following Python continuously calls the API and stores the number of viewers to a log file (make sure to add your client_id).

import requests
import json
from datetime import datetime, timedelta
import time
import logging
import argparse

CLIENTID = '<add your API key here>'

def start_logging(logfile='log.txt'):
    log = logging.getLogger()

    ch  = logging.StreamHandler()
    fh = logging.FileHandler(logfile)

    requests_log = logging.getLogger("requests")

def get_viewers(stream_name):
    url = '{0}streams/{1}?client_id={2}'.format(BASE_URL, stream_name, CLIENTID)
    r = requests.get(url)
    if r.status_code != 200:
        raise Exception("API returned {0}".format(r.status_code))
    infos = r.json()
    stream = infos['stream']
    results = {}
    if not stream:
        results = {'online':False,'title':None,'viewers':0}
        viewers = stream['viewers']
        title = stream['channel']['status']
        results = {'online':True,'title':title,'viewers':viewers}

    results['time'] ='%Y-%m-%d %H:%M:%S')
    results['stream'] = stream_name
    return results

def constant_polling(stream, onint=1,offint=5):"starting polling, inteval is " + 
        "{0}min (online) and {1}min (offline)".format(onint, offint))
    while True:
        online = False
            res = get_viewers(stream)            
            online = res['online']
            txt = json.dumps(res) 
  "Streamviewercount: {0}".format(txt))
        except Exception as e:
            logging.warn("Polling failed: {0}".format(e))            

        sleep_interval = onint if online else offint

if __name__=="__main__":
    parser = argparse.ArgumentParser(description='log viewer rating of twitch' +
        ' stream')
    parser.add_argument('channel', help='channel name')
    parser.add_argument('--int_on', help='interval if online (min)', default=1)
    parser.add_argument('--int_off', help='interval if offline (min)', default=5)
    args = parser.parse_args()
    constant_polling(, args.int_on, args.int_off)

download GIST. Sample log file output:

starting polling, inteval is 1min (online) and 5min (offline)
Streamviewercount: {"stream": "dendi", "title": "time to practice !!!  !!!!!! Dendimon", "time": "2013-12-10 17:38:10", "viewers": 24978, "online": true}
Streamviewercount: {"stream": "dendi", "title": "time to practice !!!  !!!!!! Dendimon", "time": "2013-12-10 17:39:12", "viewers": 23199, "online": true}
Streamviewercount: {"stream": "dendi", "title": "time to practice !!!  !!!!!! Dendimon", "time": "2013-12-10 17:40:15", "viewers": 21841, "online": true}
Streamviewercount: {"stream": "dendi", "title": "time to practice !!!  !!!!!! Dendimon", "time": "2013-12-10 17:41:16", "viewers": 21247, "online": true}
Streamviewercount: {"stream": "dendi", "title": null, "time": "2013-12-10 17:42:19", "viewers": 0, "online": false}
comments powered by Disqus