Piwik Analytics API: Tutorials & Examples

Piwik API Tutorial: Get Your Top 10 Keywords

This tutorial will show you how easy it is to request the yesterday’s top 10 keywords in XML format.

Build the URL

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

• your Piwik base URL (replace demo.piwik.org with the URL and path of your Piwik server
  http://demo.piwik.org/?module=API
• the name of the method you want to call. It has the format moduleName.methodToCall (see the list on API Methods). You need to request the last keywords from the plugin Referers: the method parameter is:
  method=Referers.getKeywords
• the website id.
  idSite=1
• the date parameter. This can be today, yesterday, or any date with the format YYYY-MM-DD
  date=yesterday
• the period parameter. This can be day, week, month or year
  period=day

  Alternatively, if you wanted to request all of the keywords from a given date, you could use a date range parameter. For example, to request all of the keywords since January 1st 2011:
  period=range&date=2011-01-01,yesterday

• the format parameter. Defines the output format of the data: XML, JSON, CSV, PHP (serialized PHP), HTML (simple html)
  format=xml
• (optional) the filter_limit parameter that defines the number of rows returned
  filter_limit=10

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

XML Output

Here is the output of this request:

<?xml version="1.0" encoding="utf-8" ?>
<result>
	<row>
		<label>Keyword not defined</label>
		<nb_uniq_visitors>6</nb_uniq_visitors>
		<nb_visits>6</nb_visits>
		<nb_actions>21</nb_actions>
		<max_actions>10</max_actions>
		<sum_visit_length>200</sum_visit_length>
		<bounce_count>3</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>48</idsubdatatable>
	</row>
	<row>
		<label>virtual drums</label>
		<nb_uniq_visitors>4</nb_uniq_visitors>
		<nb_visits>4</nb_visits>
		<nb_actions>8</nb_actions>
		<max_actions>5</max_actions>
		<sum_visit_length>146</sum_visit_length>
		<bounce_count>3</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>46</idsubdatatable>
	</row>
	<row>
		<label>virtual-drums.com</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>20</sum_visit_length>
		<bounce_count>1</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>55</idsubdatatable>
	</row>
	<row>
		<label>virtual drum</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>72</sum_visit_length>
		<bounce_count>1</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>44</idsubdatatable>
	</row>
	<row>
		<label>3d drumming games</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>1</nb_actions>
		<max_actions>1</max_actions>
		<sum_visit_length>0</sum_visit_length>
		<bounce_count>1</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>49</idsubdatatable>
	</row>
	<row>
		<label>drums virtual</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>2</nb_actions>
		<max_actions>2</max_actions>
		<sum_visit_length>9</sum_visit_length>
		<bounce_count>0</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>43</idsubdatatable>
	</row>
	<row>
		<label>drum virtuel</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>2</nb_actions>
		<max_actions>2</max_actions>
		<sum_visit_length>369</sum_visit_length>
		<bounce_count>0</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>42</idsubdatatable>
	</row>
	<row>
		<label>hsv rgb</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>1</nb_actions>
		<max_actions>1</max_actions>
		<sum_visit_length>0</sum_visit_length>
		<bounce_count>1</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>50</idsubdatatable>
	</row>
	<row>
		<label>http://virtual-drums.com/</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>1</nb_actions>
		<max_actions>1</max_actions>
		<sum_visit_length>0</sum_visit_length>
		<bounce_count>1</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>51</idsubdatatable>
	</row>
	<row>
		<label>poster drums</label>
		<nb_uniq_visitors>1</nb_uniq_visitors>
		<nb_visits>1</nb_visits>
		<nb_actions>2</nb_actions>
		<max_actions>2</max_actions>
		<sum_visit_length>11</sum_visit_length>
		<bounce_count>0</bounce_count>
		<nb_visits_converted>0</nb_visits_converted>
		<idsubdatatable>56</idsubdatatable>
	</row>
</result>

Other useful examples

• XML of the visits of the last 10 days, one entry per day
  http://demo.piwik.org/?module=API&method=VisitsSummary.getVisits&idSite=3&period=day&date=last10&format=xml
• XML containing keywords from the last 3 weeks, one entry per week
  http://demo.piwik.org/?module=API&method=Referers.getKeywords&idSite=3&period=week&date=last3&format=xml
• XML containing the keywords from the last 3 days which match the pattern “piwik”
  http://demo.piwik.org/?module=API&method=Referers.getKeywords&idSite=3&period=day&date=last3&format=xml&filter_column=label&filter_pattern=piwik
• RSS feed containing the top 30 keywords for the last 3 weeks, ordered by the number of actions people did when coming from these keywords
  http://demo.piwik.org/?module=API&method=Referers.getKeywords&idSite=3&period=week&date=last3&format=rss&filter_limit=30&filter_sort_column=3

You can get the data in one of these formats: XML, JSON, HTML, CSV, TSV, etc. See the API Reference for the documentation.

There are also functions for Websites, Users, Goals, PDF Reports (create, update, delete operations) and a lot more.

Check out the Piwik API Reference