Using WordPress.com stats API

Long ago I posted about the WordPress.com stats API. WordPress.com Stats API. WordPress.com 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 wordpress.com 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 WordPress.com Stats API, there was absolutely no trace or documentation about the wordpress.com API. It seemed that even the guys in wordpress.com 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 wordpress.com 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.

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: https://github.com/phoxis/codez/blob/master/wp_stats/wp_stats_demo.py

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.

./wp_stats_demo.py --id abcdef012345 --blog https://phoxis.wordpress.com/

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 wordpress.com 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 wordpress.com API.

def wp_stats_fetch (wp_api_args, file_save):

  wp_url = None;

  try:

    wp_url = make_wp_url (wp_api_args["api_key"],
                          wp_api_args["blog_id_uri"],
                          wp_api_args["table"],
                          wp_api_args["post_id"],
                          wp_api_args["end"],
                          wp_api_args["days"],
                          wp_api_args["period"],
                          wp_api_args["limit"],
                          wp_api_args["summarize"],
                          wp_api_args["form"]
                          );

    response = urllib.request.urlopen (wp_url);

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

    text = response.read().decode("utf-8");
    m = re.search ("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)");
    try:
      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]");
        else:
          #feedback_str += " [FAILED]";
          print (" [FAILED]");

        sys.stdout.flush ();

        #print (feedback_str);

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

  else:
    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 https://en.support.wordpress.com/api-keys/. Sign into https://akismet.com/, 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 https://akismet.com/resend/ 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.

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 wordpress.com 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.

UPDATE

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.