photo by xgray

After collections, the most frequently requested addition to the Flickr API has been Stats. Today, alongside access to some archived older data, we’re announcing lots of new API methods that give you access to all the stats data we’re logging.

First up is flickr.stats.getTotalViews. If we call this with no arguments, it will give you the all time view counts for a user’s photos, photostream, sets and collections:

# ?method=flickr.stats.getTotalViews

<stats>
	<total views="584957"/>
	<photos views="391325"/>
	<photostream views="175691"/>
	<sets views="17856"/>
	<collections views="85"/>
</stats>

Sounds simple right? There’s a couple of details that are worth highlighting:

• Not all Flickr members have stats enabled. If you get back an error, then someone needs to visit www.flickr.com/photos/me/stats/ and press the big pink button.
• “All time” is a surprisingly vague concept. We started recording “All-time” view counts for photos, photostreams and sets sometime back in 2006, and started recording collection counts on October 21, 2008.

Now we know how many views someone got on their account, you’ll probably want to drill down into when the views happened, where those views came from, and what photos were popular.

When

Getting details on when the views happened is simple, we can pass a date to flickr.stats.getTotalViews, and get the counts for just that that day. The date can be a unix timestamp, or something like "2010-03-24", but it has to be in the last 28 days as we don’t keep detailed data around longer than that.

What

Getting an idea of exactly what photos have been viewed is also simple – you can call flickr.stats.getPopularPhotos. This returns a standard photos response, with an extra <stats> element giving the view, comment and favorite counts. As with flickr.stats.getTotalViews, this can be called with a date if you’d like to narrow down your results to just one day.

Where

Lastly, if you want to know where the views came from, you can call flickr.stats.getPhotoDomains. This gives a list of all of the domains that sent traffic to the photo. If you want even more detail on a domain, flickr.stats.getPhotoReferrers will tell you exactly what pages we’ve seen as referrers. Both methods can be narrowed down by both date or photo id if you want to filter the results more.

But wait! There’s more!

So far we’ve only talked about detailed data for photos, because that’s all we’ve ever shown on the flickr stats pages. But, behind the scenes we’re also recording data for sets, collections and photostreams, so we’ve added API methods to get at this data too. Full details are available as part of the full API documentation.

Between them these new API methods give you programatic access to all of the data we’re recording as part of the stats system. So go ahead and make awesome things with them!