gimp_logoLong ago I posted about the stats API. Stats API. stores your blog’s raw visit stats which is available via your API key and the blog URL. Basically these stats are used to show the stats you see in your dashboard.


The older dashboard did not have much visualisations of the stats, but the new dashboard has introduced some more ways to see how your blog is doing. When I posted Stats API, there was absolutely no trace or documentation about the API. It seemed that even the guys in was not well aware about if such an API existed :D . (Check the post to know why).

At the previous post I just provided some guides on how to fetch the data. Recently I planned to write a quick implementation to fetch the stats from and therefore I am going to share the script. This is a quick and dirty implementation to demonstrate the stuff. I have also made a few processing on the incoming data and made a few plots. Most of which might not (will not) make much sense (especially the box plots), but it’s just for the baseline. Let’s proceed with the code.


Well, the main target was to get started with Python, the best way for doing so (once you know atleast another language) is to struggle through. Here is the github link for the source:

Read the comments at the beginning of the file to get the parameters.

Commandline arguments
       --id <apikey>     : Specifies the API Key
       --blog <blogurl>  : Specifies the blog URL
       --noplot          : If this switch is present, on-screen plots will not be shown
       --noget           : If this switch is present, the files will not be downloaded from web API, and local copy will be used. The local copy should be in the same directory as the script.

Note that the --id and --blog is mandatory. Others take default values. The script plots on the screen by default and stores the plots as pdfs, and fetches the stats every time the script is run. An example run is as follows.

./ --id abcdef012345 --blog

Also, make sure to run the script in Python3.

The main logic to fetch the blog information is in the initialize function. If you invoke the script without the --noget (default), then for each type of stat type of the API, wp_stats_fetch is called. The wp_stats_fetch function makes a URL according to the API’s manual by using the make_wp_url function, which it then uses to fetch the specific stat. The format can be csv, json and xml which is also configurable through the wp_api_args parameter. The wp_stats_fetch is the main function which should interest you.

I posting the current state of only the portion of the code below, which fetches the information using the API.

def wp_stats_fetch (wp_api_args, file_save):

  wp_url = None;


    wp_url = make_wp_url (wp_api_args["api_key"],

    response = urllib.request.urlopen (wp_url);

    file_ext = None;
    if wp_api_args["form"]:
      file_ext = "." + wp_api_args["form"];
      file_ext = ".csv";

    text ="utf-8");
    m = ("Error:", text);
    if m:
      raise WPStatsFetchError ("Incorrect url arguments, Error returned");
      return (-1);

    fp = open (file_save + file_ext, "w");
    fp.write (text);
    fp.close ();

  except ArgError as e:
    print (e);
    return (wp_url);

  except Exception as e:
    print (e);
    return (wp_url);

  return 0;

def initialize (my_api, my_blog, fetch_data = False):

  if (my_api is None) or (my_blog is None):
    raise ArgError ("An API key and a blog URL is mandatory");
    return (-1);

  table_list = ["views", "postviews", "referrers", "searchterms", "clicks"];
  post_id    = None;
  end        = None;
  days       = -1;
  period     = None;
  limit      = -1;
  summarize  = None;
  form       = "csv";

  req_url    = None;
  fileprefix = "stats_";

  if fetch_data is True:
    print ("\tDownloading data from web API. Overwriting local (if any)");
      wp_api_args = {
                      "api_key"     : my_api,
                      "blog_id_uri" : my_blog,
                      "table"       : None,
                      "post_id"     : post_id,
                      "end"         : end,
                      "days"        : days,
                      "period"      : period,
                      "limit"       : limit,
                      "summarize"   : summarize,
                      "form"        : form

      feedback_str = "";
      for table in table_list:
        feedback_str = "Fetching " + table + " stats";
        wp_api_args["table"] = table;
        sys.stdout.write (feedback_str),
        sys.stdout.flush ();
        retval = wp_stats_fetch (wp_api_args, fileprefix + table);

        if retval == 0:
          #feedback_str += " [SUCCESS]";
          print (" [SUCCESS]");
          #feedback_str += " [FAILED]";
          print (" [FAILED]");

        sys.stdout.flush ();

        #print (feedback_str);

    except Exception as e:
      print ("Exception: " + str (e));

    print ("\tNot fetching data from web API. Using local");

  return (True);

The API key

Replace the API key with your API key and the blog URL with your blog URL. Previously you could get API key from the Settings -> General, but now to get your API key, visit Sign into, and select the Akismet basic subscription, which costs 0$, which is free. This should show you the API key. Or if you already have it subscribed, you can visit to get the API key in your mailbox.

Some plots

These are just a few different ways to view the stats, most of the plots have no real meaning, but this code can be extended to get the results one wants.

Visit stats 2
Visit stats 2
Visit stats 1
Visit stats 1
Click Stats
Click Stats

So what now?

Nothing much actually. As these APIs do not expose country information and some other information you cannot plot the maps. Although for busy blogs the postwise stats, search terms, clicks and referrers stats can get some good insight.

Chances are I am not going to work on the script anymore, but if anyone is working or has worked on the stats API, I would be interested to check it out.

This piece of code was extended and enhanced to make a dashboard in a web interface using Django, during the Hackathon organized at The Insight Centre for Data Analytics on August 2016. We made a team and enhanced this in 36 hours non-stop marathon. The team members were Siobhán Grayson and  Gevorg Poghosyan, both researchers at The Insight Centre for Data Analytics, and ofcourse myself. We were able to do a pretty good work and had a lot of fun during that period.

  1. 01.01.2017: Added relevant portion of the code in the post. Added a little description for the relevant part of the code.
  2. 16.01.2017: Added enhancement information.

11 thoughts on “Using stats API

    1. Do you mean the visitor count or by country or other details per visitor? Stats API does not have any more details about the visitor information except the count actually. The country information you see the the dashboard is not accessible by this API, as far as I know.

        1. What you exactly mean by “overall visitors per day” is it just the count? Or also details like geographic locations?
          You can find per day post visits by doing some computation though.

        2. In wordpress stat there are views and visitor information, i can get views count by the method you provided but the visitor count, i cant find a way to get that information.

        3. Oh okay, like unique visitors which might generate more than one views per visitor. I think you still cannot get it through the API.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s