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

• using the standard REST API over HTTP
• using the Piwik PHP library files directly

Call the Piwik API using the REST API over HTTP

If you want to request data in any language (PHP, Python, Ruby, ASP, C++, Java, etc.) you can use the REST API. It is a simple way to request data via standard 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 your top 100 search engine keywords used to find your website during the current week. Here is an example in PHP:

<?php
// 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=1
$url = "http://demo.piwik.org/";
$url .= "?module=API&method=Referers.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>");
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>");
}

Here is the output of this code:

Keywords for the last month

Keyword not defined (4199 hits)
reference error piwik is not defined (27 hits)
downloads anzeigen (23 hits)
piwik forum (18 hits)
usernamen (18 hits)
exit signal segmentation fault (11) (15 hits)
child pid exit signal segmentation fault (13 hits)
how does open web analytics use cookies (12 hits)
open web analytics vs piwik (12 hits)
child pid exit signal segmentation fault (11) (11 hits)
pdo_mysql (11 hits)
piwik heatmap (10 hits)
alle downloads anzeigen (9 hits)
exit signal segmentation fault (9 hits)
forum (9 hits)
piwik joomla (9 hits)
piwik vs open web analytics (9 hits)
apache2 child pid exit segmentation fault (8 hits)
cotto vs mayweather (8 hits)
piwik (8 hits)

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 have to use this technique.

<?php
// if you don't include 'index.php', you must also define PIWIK_DOCUMENT_ROOT
// and include "libs/upgradephp/upgrade.php" and "core/Loader.php"
define('PIWIK_INCLUDE_PATH', realpath('..'));
define('PIWIK_USER_PATH', realpath('..'));
define('PIWIK_ENABLE_DISPATCH', false);
define('PIWIK_ENABLE_ERROR_HANDLER', false);
define('PIWIK_ENABLE_SESSION_START', false);
require_once PIWIK_INCLUDE_PATH . "/index.php";
require_once PIWIK_INCLUDE_PATH . "/core/API/Request.php";
Piwik_FrontController::getInstance()->init();
// This inits the API Request with the specified parameters
$request = new Piwik_API_Request('
			method=UserSettings.getResolution
			&idSite=7
			&date=yesterday
			&period=week
			&format=XML
			&filter_limit=3
			&token_auth=anonymous
');
// 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" ?>
<result>
	<row>
		<label>1920x1080</label>
		<nb_visits>355</nb_visits>
		<nb_actions>819</nb_actions>
		<max_actions>32</max_actions>
		<sum_visit_length>61306</sum_visit_length>
		<bounce_count>235</bounce_count>
		<nb_visits_converted>13</nb_visits_converted>
		<sum_daily_nb_uniq_visitors>310</sum_daily_nb_uniq_visitors>
	</row>
	<row>
		<label>1680x1050</label>
		<nb_visits>269</nb_visits>
		<nb_actions>639</nb_actions>
		<max_actions>34</max_actions>
		<sum_visit_length>32638</sum_visit_length>
		<bounce_count>168</bounce_count>
		<nb_visits_converted>10</nb_visits_converted>
		<sum_daily_nb_uniq_visitors>241</sum_daily_nb_uniq_visitors>
	</row>
	<row>
		<label>unknown</label>
		<nb_visits>245</nb_visits>
		<nb_actions>567</nb_actions>
		<max_actions>27</max_actions>
		<sum_visit_length>38090</sum_visit_length>
		<bounce_count>165</bounce_count>
		<nb_visits_converted>15</nb_visits_converted>
		<sum_daily_nb_uniq_visitors>221</sum_daily_nb_uniq_visitors>
	</row>
</result>

Include Piwik in your PHP project

You can also customize Piwik in more advanced ways, such as overriding constants, customizing the config file, and more. Learn more about Piwik advanced integration.

You may also be interested in...

• Documentation homepage
  • API Reference
  • Metadata API
  • Piwik Analytics API – Calling Techniques
  • Piwik Analytics API: Tutorials & Examples
  • Piwik API Segmentation
• FAQ