Querying the Reporting API

This guide explains how to call the Matomo (formerly Piwik) API to request your web analytics data.

Call the Matomo 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 Matomo interface
$token_auth = 'anonymous';

// we call the REST API and request the 100 first keywords for the last month for the idsite=7
$url = "https://demo.matomo.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, 'UTF-8'), ENT_QUOTES, 'UTF-8');
    $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> (10190 hits)<br>
<b>actions.getdownloads</b> (1 hits)<br>
<b>count parameter must be an array codeigniter</b> (1 hits)<br>
<b>dexing.dexarchivebuilderexception</b> (1 hits)<br>
<b>error: you can&#039;t access this resource as it requires view access for at least one website.</b> (1 hits)<br>
<b>facebook app user agnt</b> (1 hits)<br>
<b>finde firefix widgets nicht</b> (1 hits)<br>
<b>getattributioncampaignname()</b> (1 hits)<br>
<b>get matomo for raspberry pi</b> (1 hits)<br>
<b>hindi video xxxx karua tel flooring</b> (1 hits)<br>
<b>how to track affiliate link click using javascript</b> (1 hits)<br>
<b>mail for not wrting daily updates</b> (1 hits)<br>
<b>matomo api hls</b> (1 hits)<br>
<b>matomo cs cart</b> (1 hits)<br>
<b>matomo forum</b> (1 hits)<br>
<b>matomo import log ssl certificate</b> (1 hits)<br>
<b>matomo vs open web analytics</b> (1 hits)<br>
<b>pdo_mysql not loaded</b> (1 hits)<br>
<b>piwik bisher wurden keine daten aufgezeichnet</b> (1 hits)<br>
<b>piwik delete events</b> (1 hits)<br>

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.