Friendly warning: blog post for software geeks only!

What is an “API” in Piwik and how to use it?

In Piwik, every plugin can expose its own API. Creating an API in a Piwik plugin is as easy as creating a class in a file called API.php; see example of the UserCountry/API.php API.

This class is then automatically loaded in Piwik and the public methods of the class are automatically available to call as a REST web service. For example, to call the method

public function getCountry( $idSite, $period, $date )

You can simply call:

index.php?module=API&method=UserCountry.getCountry&idSite=1&period=day&date=yesterday&format=xml&token_auth=X

You can see that the parameters idSite, date and period are automatically mapped from the URL to the original php function. This is where the magic happens, using the PHP Reflection API.

The page piwik/index.php?module=API&action=listAllAPI, available from the “API” link in the top bar of the Piwik user interface, will load all plugins API files, and automatically generate the “documentation”, with example links to the calls.

How is this automatic REST API implemented in PHP5?

I have published a quick presentation about the concept behind the implementation of this API code. Here is the embed presentation:

You can also see the presentation on slideshare: “Easy rest service using PHP reflection api – on slideshare”

All the code used for this API functionnality is located in piwik/core/API/* ; you can browse this code online in the Piwik code browser. Feel free to reuse this code in your project, and submit any patch that you may have to the Piwik team.

If you’re interested by this topic, see also the blog post: How to design an API?

Let us know your feedback or questions.


Matthieu Aubry

While studying in India in 2006, Matthieu had the idea of creating an open source web analytics alternative to Google Analytics. In 2007 he released the first public beta version of Piwik. Matthieu now leads the project from New Zealand, where he likes to spend his days coding new features from the Piwik Roadmap, and helping users and customers use Piwik effectively. Find him on twitter or github.