1. Get the data from Piwik: call the API!
  2. Tutorial: get the top 10 keywords
    1. Build the URL
  3. Other documentation about the API

Get the data from Piwik: call the API!

Open APIs means a lot for us. You can get all the data very easily by calling one of these APIs. There are different ways of calling the API, depending on the technology you are using.

Piwik APIs makes it easy to get:

  • the search engines keywords used during the last week
  • the top 5 browsers of the current year
  • the top 10 pages of your website that contain the string "blog", ordered by number of visits ascending
  • the list of the websites registered in Piwik or the list of users that have an admin access on the website no 4
  • and a lot more

You can get the data in one of these formats:

  • XML
  • JSON
  • CSV
  • serialized PHP
  • simple html

Tutorial: get the top 10 keywords

This tutorial will tell you how to request the top 10 keywords of yesterday in XML format.

Build the URL

To build the URL of the API call, you need:

  • your piwik base URL

Example: http://piwik.org/demo/?module=API

  • the name of the method you want to call. It has format moduleName.methodToCall (see the list on API Methods)

Example: you want to get the last keywords from the plugin Referers. The method parameter is method=Referers.getKeywords

  • the website id.

Example: idSite=1

  • the date parameter. It can be today, yesterday, or any date with the format YYYY-MM-DD

Example: date=yesterday

  • the period parameter. It can be day, week, month or year

Example: period=day

  • the format parameter. Defines the output format of the data: XML, JSON, CSV, PHP (serialized PHP), HTML (simple html)

Example: format=xml

  • (optional) the filter_limit parameter that defines the number of rows returned

Example: filter_limit=10

The final url is http://piwik.org/demo/?module=API&method=Referers.getKeywords&idSite=1&date=yesterday&period=day&format=xml&filter_limit=10

Here is the output of this request: 

<?xml version="1.0" encoding="utf-8" ?>
<result>
        <row>
                <label>piwik</label>
                <nb_uniq_visitors>95</nb_uniq_visitors>
                <nb_visits>99</nb_visits>
                <nb_actions>580</nb_actions>
                <max_actions>39</max_actions>
                <sum_visit_length>39886</sum_visit_length>
                <bounce_count>23</bounce_count>
                <idsubdatatable>149</idsubdatatable>
        </row>
        <row>
                <label>web+analytics</label>
                <nb_uniq_visitors>23</nb_uniq_visitors>
                <nb_visits>23</nb_visits>
                <nb_actions>86</nb_actions>
                <max_actions>24</max_actions>
                <sum_visit_length>4068</sum_visit_length>
                <bounce_count>13</bounce_count>
                <idsubdatatable>290</idsubdatatable>
        </row>
        <row>
                <label>analytics</label>
                <nb_uniq_visitors>14</nb_uniq_visitors>
                <nb_visits>14</nb_visits>
                <nb_actions>34</nb_actions>
                <max_actions>8</max_actions>
                <sum_visit_length>1063</sum_visit_length>
                <bounce_count>7</bounce_count>
                <idsubdatatable>158</idsubdatatable>
        </row>
        <row>
                <label>89</label>
                <nb_uniq_visitors>8</nb_uniq_visitors>
                <nb_visits>8</nb_visits>
                <nb_actions>8</nb_actions>
                <max_actions>1</max_actions>
                <sum_visit_length>80</sum_visit_length>
                <bounce_count>8</bounce_count>
                <idsubdatatable>155</idsubdatatable>
        </row>
        <row>
                <label>web+2.0</label>
                <nb_uniq_visitors>5</nb_uniq_visitors>
                <nb_visits>5</nb_visits>
                <nb_actions>11</nb_actions>
                <max_actions>5</max_actions>
                <sum_visit_length>266</sum_visit_length>
                <bounce_count>3</bounce_count>
                <idsubdatatable>283</idsubdatatable>
        </row>
        <row>
                <label>free+web+analytics</label>
                <nb_uniq_visitors>4</nb_uniq_visitors>
                <nb_visits>4</nb_visits>
                <nb_actions>8</nb_actions>
                <max_actions>4</max_actions>
                <sum_visit_length>1235</sum_visit_length>
                <bounce_count>2</bounce_count>
                <idsubdatatable>182</idsubdatatable>
        </row>
        <row>
                <label>open+source+web+analytics</label>
                <nb_uniq_visitors>3</nb_uniq_visitors>
                <nb_visits>3</nb_visits>
                <nb_actions>38</nb_actions>
                <max_actions>20</max_actions>
                <sum_visit_length>1179</sum_visit_length>
                <bounce_count>1</bounce_count>
                <idsubdatatable>215</idsubdatatable>
        </row>
        <row>
                <label>non-static+method+should+not+be+called+statically</label>
                <nb_uniq_visitors>2</nb_uniq_visitors>
                <nb_visits>2</nb_visits>
                <nb_actions>3</nb_actions>
                <max_actions>2</max_actions>
                <sum_visit_length>28</sum_visit_length>
                <bounce_count>1</bounce_count>
                <idsubdatatable>208</idsubdatatable>
        </row>
        <row>
                <label>web+analytics+</label>
                <nb_uniq_visitors>2</nb_uniq_visitors>
                <nb_visits>2</nb_visits>
                <nb_actions>2</nb_actions>
                <max_actions>1</max_actions>
                <sum_visit_length>20</sum_visit_length>
                <bounce_count>2</bounce_count>
                <idsubdatatable>291</idsubdatatable>
        </row>
        <row>
                <label>open+source+analytics+</label>
                <nb_uniq_visitors>2</nb_uniq_visitors>
                <nb_visits>2</nb_visits>
                <nb_actions>7</nb_actions>
                <max_actions>4</max_actions>
                <sum_visit_length>539</sum_visit_length>
                <bounce_count>0</bounce_count>
                <idsubdatatable>211</idsubdatatable>
        </row>
</result>

Other documentation about the API