WordPress.com Stats API


gimp_logoWordPress.com has a very nice stat plugin showing the overall post views data and also post by post, but it would be always great if there was more. A lot of people talk about introducing Google Analytics. A lot of people save the data offline by copying the summary tables into files to save the site data. I had an idea to process the data of my site a bit differently and find trends in the data. I thought except copy-pasting the site summary data, there should be a cleaner manner to store the data. First I made a brief Google search, then made a wordpress.com forums thread. Then i had a short chat with Mark in wordpress.com freenode IRC and was redirected to wp.com email support. The first result came from email support telling that there is no data export feature. But another email followed to correct the previous one which told about the wordpress.com stats API with which you can get your wordpress.com site’s stats data in CSV or XML format.

The thing

You can get the wordpress.com stats API here : http://stats.wordpress.com/csv.php
When you visit this page you would get a list of GET parameters with which you can generate different queries and get different data as per your needs. For example, post specific data, data between certain time or completely as a whole etc.
To use this API you would need your wordpress.com API key which you were assigned when you first registered. You can get your wordpress.com API key from Akismet Here : https://akismet.com/resend/

Here is the summary of the GET parameters to the link (from http://stats.wordpress.com/csv.php)
Parameters:

Parameter Type Details
api_key String A secret unique to your WordPress.com user account.
blog_id Integer The number that identifies your blog. Find it in other stats URLs.
blog_uri String The full URL to the root directory of your blog. Including the full path.
table String One of views, postviews, referrers, searchterms, clicks, videoplays.
post_id Integer For use with postviews table.
end String The last day of the desired time frame. Format is ‘Y-m-d’ (e.g.2007-05-01) and default is UTC date.
days Integer The length of the desired time frame. Default is 30. “-1″ means unlimited.
period String For use with views table and the ‘days’ parameter. The desired time period grouping. ‘week’ or ‘month’ Use ‘days’ as the number of results to return (e.g. ‘&period=week&days=12′ to return 12 weeks)
limit Integer The maximum number of records to return. Default is 100. “-1″ means unlimited. If days is -1, limit is capped at 500.
summarize Flag If present, summarizes all matching records.
format String The format the data is returned in, ‘csv’ or ‘xml’. Default is ‘csv’.

The mandatory parameters are the api_key, blog_uri or the blog_id. Note that you need to provide either the blog_id or the blog_uri . The post_id is the one which is assigned to each post. You can get the post ids from your post dash board by inspecting the post edit link.

The table parameter can take one of the 6 strings: views, postviews, referrers, searchterms, clicks, videoplays. The views parameter gets the overall views per day of your blog in (date,views) format. The postviews parameter gives you stats is (date,post_id,post_title,post_permalink,views) format. The referrs shows stats in (date,referrer,views) format. The searchterms gives stats in (date,searchterm,views) format.

You can also get a post specific stat with the post_id parameter. Provide here the post id and make the table parameter to postviews. This will fetch stats for that post in (date, views) format.

You can specify the number of records to return with the days parameter. Also the period parameter lets you select the to return weekly or monthly stats. Like if you set period=week then the query would return the visits in (week of year, vist) format. Similarly setting period=month would return the month wise visits. You can get stats upto some specific dates with the end parameter.

By default the queries return in CSV format, but you can get the results in XML format by setting the parameter format to format=xml

For example

  • To find the visits to your blog in last 100 days:
    Query: with table=views, days=100

    
    http://stats.wordpress.com/csv.php?api_key=abcdef123456&blog_uri=http://yourblog.wordpress.com&table=views&days=100
    
    
  • To get day wise views to your blog since its birth in XML format
    Query: with table=views, limit=-1, days=-1, format=xml

    
    http://stats.wordpress.com/csv.php?api_key=abcdef123456&blog_id=0&blog_uri=http://yourblog.wordpress.com&table=views&limit=-1&days=-1&format=xml
    
    

    Note that in this query the limit of the days returned is 500. If you set the days to -1 and limit to -1 then the limit is capped to 500 (as per the table).

  • To get visits since beginning of the blog till this day grouped by week&
    Query: with table=views, period=week, days=-1, limit=-1

    
    http://stats.wordpress.com/csv.php?api_key=abcdef123456&blog_id=0&blog_uri=http://yourblog.wordpress.com&table=views&period=week&days=-1&limit=-1
    
    
  • To get the summarized total visits till now use the summarize flag and days=-1

    
    http://stats.wordpress.com/csv.php?api_key=abcdef123456&blog_uri=http://yourblog.wordpress.com&table=views&days=-1&summarize
    
    

    To get summary for some other date range adjust the end , days parameters.

For all the queries set your api_key, blog_id and the blog_uri . You need to provide the parameters separated by &

Pardon me for these horrible queries, these were just a demo to show how it works, you have to work out the other stuffs and how you can make it work as per your requirement. Also have a look at this for some more info http://wiki.forum.nokia.com/index.php/API_and_demo_application_for_accessing_Wordpress_statistics

I hope this would help a lot of people wanting to get their stats offline, or access the wordpress.com blog stats with their application.

The Email

Here is the email i sent to wp.com support and the reply

My Email

Hello,
I was thinking about a feature which is the availability of the past data of a blog in a downloadable CSV or a Spreadsheet format. I posted about this in the forum but there was no answer. Optionally how about including a regression curve, most preferably a line which indicates the overall progress of the blog in a daily , monthly and yearly basis along with the existing stats. The existing stats gets a good overview. But if there is a regression line through the data points then it would be great to see the progress at a glance. I asked about this in the wordpress.com IRC channel to Mark, he told me to email wordpress.com support and ask this email to forward to Andy, who is behind the wordpress.com stats programming.

Reply1

Hi Arjon

If I understand correctly, you are talking about an option to export data from the Stats feature?

This feature is not currently available, but I will post your thoughts to our internal ideas blog. If enough people like it, it will eventually get added to WordPress.com

Please contact us again if you have any more questions.


Ran,
WordPress.com, Support

Reply2

Hi again Arjon

Sorry for misleading you here – when I posted to our ideas blog, another worker allerted me to the fact that we do already provide a way to export stats data to CSV, using a simple API:

http://stats.wordpress.com/csv.php

You can see some examples for using this API here:

http://wiki.forum.nokia.com/index.php/API_and_demo_application_for_accessing_Wordpress_statistics

Hope this helps!


Ran,
WordPress.com, Support

About these ads

About phoxis

Homo-sapiens
This entry was posted in GNU+Linux+FOSS, Tutorials and tagged , , . Bookmark the permalink.

14 Responses to WordPress.com Stats API

  1. Pothi says:

    Wow. There is a lot to explore in WP.com stat plugin. That is a useful stuff. I didn’t know this earlier too. Thanks for sharing.

  2. gamerwho says:

    Hmm, I really need to host my blog on a shared/dedicated server some time… These WP plugins are great! Especially this plugin is great! Nice post.

    • phoxis says:

      Why do you want to go for shared? This plugin is available already on your wp.com dashboard the stats. You can use this plugin to download the stats or use the stats somewhere else. I recommend staying with wp.com because it provides a lot of useful plugins and features. I have tried some other platforms and not have settled in wordpress.com , bought a domain and the domain mapping feature of wordpress.com

  3. Jennifer says:

    Oh, very nice! Thank you for pursuing this and even more so for writing it up.

  4. Tomas says:

    Hi, thanks for your post!
    I’m interesting getting stats to work in a multi site install and collect last weeks unique visitors for each blog…ending up in a toplist. Do you think it’s possible through the API?

    Regards
    Tomas

    • phoxis says:

      I haven’t worked with the wordpress.com API, but you can access the stats of different wp.com blogs owned by you and then operate on the fetched data. All the sites from which you will be fetching data should be owned by you, and you need to provide the API key of your wp.com account. With appropriate parameters to the API fetch the total visit of one day , month, or week, and then sort the fetched numbers and you can have a toplist. Give your API key in the api_key parameter and for each blog specify the blog links with the blog_uri parameter, and then fetch the visit stats as per your requirement. Checkout the post for it and also the API webpage. But wp.com API will not fetch unique visitor tracks with IP address, it just will get you the number of visitors. Note that because wp.com will not allow any kind of code to be run in wp.com servers therefore this toplist calculation needs to be somewhere else.

  5. Tomas says:

    Thanks phoix!
    Will do some tests…

  6. Pingback: Accessing fine-grained stats on Wordpress « Nate Shiff

  7. Lillah says:

    Alakazaam-infromtaion found, problem solved, thanks!

  8. Pingback: wordpress.comでgoogle analyticsが使えない « 實松アウトプット

  9. Pingback: WordPress com Stats API General description — Jetpack for WordPress

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s