Context Navigation

Calling the API

Calling the API

This page explains the two ways to call the Piwik API to request your web analytics data: internal call or external (internet http) call

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, it is highly advisable to use an encrypted request. Otherwise, your token_auth is exposed to eavesdroppers. It can be achieved using https instead of http. In the following example, replace the string "http" by "https".

You can for example get the 100 best search engines keywords used on 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=1&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 = urldecode($row['label']);
    $hits = $row['nb_visits'];
    print("<b>$keyword</b> ($hits hits)<br>");
}

Here is the output of this code:

Keywords for the last month

piwik (195 hits)
analytics (8 hits)
website analytics (6 hits)
google analytics alternative (5 hits)
google analytics open source (4 hits)
web analytics (3 hits)
open source analytics (3 hits)
piwiki (3 hits)
piwick (3 hits)
open flash chart error #2032 (2 hits)
piwik css caching (2 hits)
fatal error: allowed memory size of 268435456 bytes exhausted (2 hits)
theme (2 hits)
how to set up a php environment (2 hits)
google analytics api (2 hits)
web analytic (2 hits)
open source web analytics (2 hits)
piwik mobile site (2 hits)
piwik plugins (2 hits)
pwik (2 hits)

Call the Piwik API in PHP

This is the most efficient technique as it doesn't go over http. You basically directly call the PHP runtime and get the PHP data structure back.

If you want to request data in a PHP script that is on the same server as Piwik, you can use this simple technique.

If you are developing a plugin, you have to use this technique.

<?php
define('PIWIK_INCLUDE_PATH', '..');
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=1
            &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>1280x1024</label>
                <nb_visits>2241</nb_visits>
                <nb_actions>6859</nb_actions>
                <max_actions>210</max_actions>
                <sum_visit_length>391590</sum_visit_length>
                <bounce_count>1378</bounce_count>
                <nb_visits_converted>567</nb_visits_converted>
                <sum_daily_nb_uniq_visitors>1681</sum_daily_nb_uniq_visitors>
        </row>
        <row>
                <label>1680x1050</label>
                <nb_visits>1859</nb_visits>
                <nb_actions>5546</nb_actions>
                <max_actions>74</max_actions>
                <sum_visit_length>423930</sum_visit_length>
                <bounce_count>1080</bounce_count>
                <nb_visits_converted>500</nb_visits_converted>
                <sum_daily_nb_uniq_visitors>1536</sum_daily_nb_uniq_visitors>
        </row>
        <row>
                <label>1280x800</label>
                <nb_visits>1494</nb_visits>
                <nb_actions>3930</nb_actions>
                <max_actions>38</max_actions>
                <sum_visit_length>273664</sum_visit_length>
                <bounce_count>910</bounce_count>
                <nb_visits_converted>384</nb_visits_converted>
                <sum_daily_nb_uniq_visitors>1227</sum_daily_nb_uniq_visitors>
        </row>
</result>

Include Piwik from your PHP project

You can also directly include Piwik index.php in your project. Learn more about this advanced integration.