Querying the Reporting API

This guide explains how to call the Piwik API to request your web analytics data. There are two methods:

  • using the standard HTTP API
  • using Piwik's PHP code directly

Call the Piwik API using the HTTP API

If you want to request data in any language (PHP, Python, Ruby, ASP, C++, Java, etc.) you can use the HTTP API. It is a simple way to request data via an HTTP GET.

Security Notice

If the API call requires the token_auth and the HTTP request is sent over untrusted networks, we highly advise that you use an encrypted request. Otherwise, your token_auth is exposed to eavesdroppers. This can be done using https instead of http. In the following example, replace the string "http" by "https".

You can, for example, get the top 100 search engine keywords used to find your website during the current week. Here is an example in PHP:

exit; // REMOVE this line to run the script

// this token is used to authenticate your API request.
// You can get the token on the API page inside your Piwik interface
$token_auth = 'anonymous';

// we call the REST API and request the 100 first keywords for the last month for the idsite=7
$url = "http://demo.piwik.org/";
$url .= "?module=API&method=Referrers.getKeywords";
$url .= "&idSite=7&period=month&date=yesterday";
$url .= "&format=PHP&filter_limit=20";
$url .= "&token_auth=$token_auth";

$fetched = file_get_contents($url);
$content = unserialize($fetched);

// case error
if (!$content) {
    print("Error, content fetched = " . $fetched);

print("<h1>Keywords for the last month</h1>\n");
foreach ($content as $row) {
    $keyword = htmlspecialchars(html_entity_decode(urldecode($row['label']), ENT_QUOTES), ENT_QUOTES);
    $hits = $row['nb_visits'];

    print("<b>$keyword</b> ($hits hits)<br>\n");

Here is the output of this code:

<h1>Keywords for the last month</h1>
<b>Keyword not defined</b> (4157 hits)<br>
<b>http://1.1.1./login.html</b> (3 hits)<br>
<b>xxxxxxxxxxxx.com</b> (3 hits)<br>
<b>wwwxxxxcom</b> (2 hits)<br>
<b>&quot;error while sending query packet&quot;</b> (1 hits)<br>
<b>.htaccess prevent folder access from outside</b> (1 hits)<br>
<b>1</b> (1 hits)<br>
<b>1.1.1/log in</b> (1 hits)<br>
<b>2015 uname safemode drwx febuary</b> (1 hits)<br>
<b>ailed to write session data (files). please verify that the current setting of session.save_path is correct (/tmp) in unknown on line 0</b> (1 hits)<br>
<b>alle downloads anzeigen</b> (1 hits)<br>
<b>archivtemp</b> (1 hits)<br>
<b>download tracker php free scripts</b> (1 hits)<br>
<b>error: form security failed. please reload the&hellip;</b> (1 hits)<br>
<b>failed (104: connection reset by peer)</b> (1 hits)<br>
<b>genrate master password for my administrator password</b> (1 hits)<br>
<b>get request to piwik.php failed 500</b> (1 hits)<br>
<b>google captcha warning</b> (1 hits)<br>
<b>how to reset site timing?</b> (1 hits)<br>
<b>how to track who download file in php</b> (1 hits)<br>

Call the Piwik API in PHP

If you want to request data in a PHP script that is on the same server as Piwik, you can use this simple technique. This is a more efficient solution as it doesn't require network calls. You directly call the PHP Piwik runtime and get the PHP data structure back.

If you are developing a plugin, you should be using this technique. Please note that including index.php will set the default timezone of the calling code to UTC.

use Piwik\API\Request;
use Piwik\FrontController;

define('PIWIK_INCLUDE_PATH', realpath('../..'));
define('PIWIK_USER_PATH', realpath('../..'));
define('PIWIK_ENABLE_DISPATCH', false);

// if you prefer not to include 'index.php', you must also define here PIWIK_DOCUMENT_ROOT
// and include "libs/upgradephp/upgrade.php" and "core/Loader.php"
require_once PIWIK_INCLUDE_PATH . "/index.php";
require_once PIWIK_INCLUDE_PATH . "/core/API/Request.php";

$environment = new \Piwik\Application\Environment(null);


// This inits the API Request with the specified parameters
$request = new Request('
// Calls the API and fetch XML data back
$result = $request->process();
echo $result;

Here is the output of this script:

<?xml version="1.0" encoding="utf-8" ?>

Learn more

To learn more about all the options available when calling the reporting API, read the Reporting API reference.

You can also have a look at the list of client libraries available to call the reporting API.