From the beginning, the stats API has been powerful and always allowed you to extract every piece of data available via our web site into several common formats for a variety of applications. However, if you wanted to “recreate” Clicky within your own desktop appllcation (and we know there are at least 3 of you working on something like that right now), you had to make a seperate request for each type of data you wanted.
This is bad for us because it creates significantly more load on our servers, and bad for you because it makes your application slower. Version 3 of the API fixes this, and allows you get multiple (unlimited) data types with a single request, by seperating them with commas. Here is an example request that you could use to build a simple dashboard for “today”, with a single request. This would have taken 5 requests with the old API:
Another item that needed fixing was that if you requested a date range, the results returned would always be the total/sum from that entire date range. The only way to get “daily” values was to make seperate requests for each date – again, bad for us, and bad for you. Version 3 has a new parameter called “daily” that, if set, will return the results on a per-day basis, instead of the sum.
Here is the same request as above, with “daily” vallues, for the entire month of June. With version 2 of the API, this would have required 150 different requests. Now we can get it with one: http://api.getclicky.com/stats/api3?site_id=32020&sitekey=2e05fe2778b6&type=visitors,actions,actions-average,time-average,bounce-rate&date=2008-06&daily=1
The last major new feature is support for callbacks and variable assignments for JSON output. This lets you skirt around annoying JavaScript “security” issues when it comes to cross-domain stuff. Please see the docs for full details and examples.
All of these changes required changing the structure of the results, too. Instead of just a bunch of items, the items now have a date wrapper for each date, and each date has a type wrapper for each type. Those of you familiar with the API already should be able to spot the new formatting in the screenshot below. This new formatting is used even if you only request one type on one specific date, so that your code can work the same for every possible request you could make.
The API documentation has been updated with everything that’s new (there are a few other minor things). It also includes a bunch of new sample requests that showcase the new features. The new URL for the API is api3 instead of api2, but api2 continues to work indefinitely, of course.