Tutorial: Get your top 10 keywords
This documentation is for an outdated Matomo version.
Click here if you want to read this article for the latest version.
Click here if you want to read this article for the latest version.
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 Matomo (formerly Piwik) base URL (replace demo.matomo.org with the URL and path of your Matomo server
https://demo.matomo.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 Referrers:
method=Referrers.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 keywords from a given date, you could use a date range parameter. For example, to request all keywords since January 1st 2011:
period=range&date=2011-01-01,yesterdaythe 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 https://demo.matomo.org/?module=API&method=Referrers.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>333</nb_uniq_visitors>
<nb_visits>372</nb_visits>
<nb_actions>844</nb_actions>
<nb_users>27</nb_users>
<max_actions>6</max_actions>
<sum_visit_length>23870</sum_visit_length>
<bounce_count>135</bounce_count>
<nb_visits_converted>71</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>11</nb_conversions>
<nb_visits_converted>11</nb_visits_converted>
<revenue>0</revenue>
<items>16</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>12</nb_conversions>
<nb_visits_converted>12</nb_visits_converted>
<revenue>152</revenue>
<revenue_subtotal>152</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>17</items>
</row>
<row idgoal='1'>
<nb_conversions>8</nb_conversions>
<nb_visits_converted>8</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>9</nb_conversions>
<nb_visits_converted>9</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='3'>
<nb_conversions>14</nb_conversions>
<nb_visits_converted>14</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>11</nb_conversions>
<nb_visits_converted>11</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='6'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='7'>
<nb_conversions>4</nb_conversions>
<nb_visits_converted>4</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>11</nb_conversions>
<nb_visits_converted>11</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>71</nb_conversions>
<revenue>152</revenue>
<nb_visits_percent_of_total>44.1%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>42.6%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>37.8%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>37.8%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>50.2%</bounce_count_percent_of_total>
<revenue_percent_of_total>46.9%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==</segment>
<idsubdatatable>1</idsubdatatable>
</row>
<row>
<label>scuba diving meaning</label>
<nb_uniq_visitors>193</nb_uniq_visitors>
<nb_visits>193</nb_visits>
<nb_actions>432</nb_actions>
<nb_users>14</nb_users>
<max_actions>8</max_actions>
<sum_visit_length>12573</sum_visit_length>
<bounce_count>60</bounce_count>
<nb_visits_converted>46</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>11</nb_conversions>
<nb_visits_converted>11</nb_visits_converted>
<revenue>0</revenue>
<items>19</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>11</nb_conversions>
<nb_visits_converted>11</nb_visits_converted>
<revenue>113</revenue>
<revenue_subtotal>113</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>15</items>
</row>
<row idgoal='1'>
<nb_conversions>7</nb_conversions>
<nb_visits_converted>7</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>5</nb_conversions>
<nb_visits_converted>5</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='3'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='6'>
<nb_conversions>5</nb_conversions>
<nb_visits_converted>5</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='7'>
<nb_conversions>7</nb_conversions>
<nb_visits_converted>7</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>7</nb_conversions>
<nb_visits_converted>7</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>46</nb_conversions>
<revenue>113</revenue>
<nb_visits_percent_of_total>22.9%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>21.8%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>24.5%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>24.5%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>22.3%</bounce_count_percent_of_total>
<revenue_percent_of_total>34.9%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==m%C3%A9diath%C3%A8que+clairvault</segment>
<idsubdatatable>8</idsubdatatable>
</row>
<row>
<label>diving facts</label>
<nb_uniq_visitors>94</nb_uniq_visitors>
<nb_visits>94</nb_visits>
<nb_actions>249</nb_actions>
<nb_users>8</nb_users>
<max_actions>6</max_actions>
<sum_visit_length>6638</sum_visit_length>
<bounce_count>23</bounce_count>
<nb_visits_converted>22</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
<items>2</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>3</nb_conversions>
<nb_visits_converted>3</nb_visits_converted>
<revenue>23</revenue>
<revenue_subtotal>23</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>3</items>
</row>
<row idgoal='1'>
<nb_conversions>3</nb_conversions>
<nb_visits_converted>3</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>5</nb_conversions>
<nb_visits_converted>5</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='3'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='7'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>5</nb_conversions>
<nb_visits_converted>5</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>22</nb_conversions>
<revenue>23</revenue>
<nb_visits_percent_of_total>11.2%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>12.6%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>11.7%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>11.7%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>8.6%</bounce_count_percent_of_total>
<revenue_percent_of_total>7.1%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==biblioth%C3%A8que+clairvault+horaires</segment>
<idsubdatatable>6</idsubdatatable>
</row>
<row>
<label>diving magazine</label>
<nb_uniq_visitors>37</nb_uniq_visitors>
<nb_visits>37</nb_visits>
<nb_actions>94</nb_actions>
<nb_users>1</nb_users>
<max_actions>5</max_actions>
<sum_visit_length>2919</sum_visit_length>
<bounce_count>7</bounce_count>
<nb_visits_converted>14</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
<items>3</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>10</revenue>
<revenue_subtotal>10</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>2</items>
</row>
<row idgoal='1'>
<nb_conversions>4</nb_conversions>
<nb_visits_converted>4</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>3</nb_conversions>
<nb_visits_converted>3</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='6'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='7'>
<nb_conversions>3</nb_conversions>
<nb_visits_converted>3</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>14</nb_conversions>
<revenue>10</revenue>
<nb_visits_percent_of_total>4.4%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>4.7%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>7.4%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>7.4%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>2.6%</bounce_count_percent_of_total>
<revenue_percent_of_total>3.1%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==r%C3%A9server+livre+biblioth%C3%A8que</segment>
<idsubdatatable>9</idsubdatatable>
</row>
<row>
<label>diving certification</label>
<nb_uniq_visitors>35</nb_uniq_visitors>
<nb_visits>35</nb_visits>
<nb_actions>83</nb_actions>
<nb_users>3</nb_users>
<max_actions>5</max_actions>
<sum_visit_length>2431</sum_visit_length>
<bounce_count>7</bounce_count>
<nb_visits_converted>10</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
<items>1</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>3</revenue>
<revenue_subtotal>3</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>1</items>
</row>
<row idgoal='1'>
<nb_conversions>6</nb_conversions>
<nb_visits_converted>6</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='3'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>10</nb_conversions>
<revenue>3</revenue>
<nb_visits_percent_of_total>4.2%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>4.2%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>5.3%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>5.3%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>2.6%</bounce_count_percent_of_total>
<revenue_percent_of_total>0.9%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==cin%C3%A9-club+clairvault</segment>
<idsubdatatable>4</idsubdatatable>
</row>
<row>
<label>scuba diving gear</label>
<nb_uniq_visitors>32</nb_uniq_visitors>
<nb_visits>32</nb_visits>
<nb_actions>83</nb_actions>
<nb_users>1</nb_users>
<max_actions>5</max_actions>
<sum_visit_length>2896</sum_visit_length>
<bounce_count>8</bounce_count>
<nb_visits_converted>9</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>3</nb_conversions>
<nb_visits_converted>3</nb_visits_converted>
<revenue>0</revenue>
<items>6</items>
</row>
<row idgoal='2'>
<nb_conversions>6</nb_conversions>
<nb_visits_converted>6</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>9</nb_conversions>
<revenue>0</revenue>
<nb_visits_percent_of_total>3.8%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>4.2%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>4.8%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>4.8%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>3%</bounce_count_percent_of_total>
<revenue_percent_of_total>0%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==mediatheque+lumiere</segment>
<idsubdatatable>3</idsubdatatable>
</row>
<row>
<label>scuba</label>
<nb_uniq_visitors>30</nb_uniq_visitors>
<nb_visits>30</nb_visits>
<nb_actions>81</nb_actions>
<nb_users>1</nb_users>
<max_actions>8</max_actions>
<sum_visit_length>2831</sum_visit_length>
<bounce_count>6</bounce_count>
<nb_visits_converted>5</nb_visits_converted>
<goals>
<row idgoal='ecommerceAbandonedCart'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
<items>1</items>
</row>
<row idgoal='ecommerceOrder'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>23</revenue>
<revenue_subtotal>23</revenue_subtotal>
<revenue_tax>0</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>0</revenue_discount>
<items>4</items>
</row>
<row idgoal='2'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='6'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='7'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>5</nb_conversions>
<revenue>23</revenue>
<nb_visits_percent_of_total>3.6%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>4.1%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>2.7%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>2.7%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>2.2%</bounce_count_percent_of_total>
<revenue_percent_of_total>7.1%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==horaires+m%C3%A9diath%C3%A8que+lumi%C3%A8re</segment>
<idsubdatatable>7</idsubdatatable>
</row>
<row>
<label>diving lessons</label>
<nb_uniq_visitors>25</nb_uniq_visitors>
<nb_visits>25</nb_visits>
<nb_actions>51</nb_actions>
<nb_users>6</nb_users>
<max_actions>6</max_actions>
<sum_visit_length>810</sum_visit_length>
<bounce_count>14</bounce_count>
<nb_visits_converted>6</nb_visits_converted>
<goals>
<row idgoal='1'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='5'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='6'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>6</nb_conversions>
<revenue>0</revenue>
<nb_visits_percent_of_total>3%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>2.6%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>3.2%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>3.2%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>5.2%</bounce_count_percent_of_total>
<revenue_percent_of_total>0%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==emprunter+dvd+m%C3%A9diath%C3%A8que</segment>
<idsubdatatable>2</idsubdatatable>
</row>
<row>
<label>scuba diving dangers</label>
<nb_uniq_visitors>25</nb_uniq_visitors>
<nb_visits>25</nb_visits>
<nb_actions>62</nb_actions>
<nb_users>0</nb_users>
<max_actions>6</max_actions>
<sum_visit_length>1813</sum_visit_length>
<bounce_count>9</bounce_count>
<nb_visits_converted>5</nb_visits_converted>
<goals>
<row idgoal='1'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='2'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='3'>
<nb_conversions>1</nb_conversions>
<nb_visits_converted>1</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal='8'>
<nb_conversions>2</nb_conversions>
<nb_visits_converted>2</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>5</nb_conversions>
<revenue>0</revenue>
<nb_visits_percent_of_total>3%</nb_visits_percent_of_total>
<nb_actions_percent_of_total>3.1%</nb_actions_percent_of_total>
<nb_visits_converted_percent_of_total>2.7%</nb_visits_converted_percent_of_total>
<nb_conversions_percent_of_total>2.7%</nb_conversions_percent_of_total>
<bounce_count_percent_of_total>3.3%</bounce_count_percent_of_total>
<revenue_percent_of_total>0%</revenue_percent_of_total>
<segment>referrerType==search;referrerKeyword==agenda+culturel+clairvault</segment>
<idsubdatatable>5</idsubdatatable>
</row>
</result>
Other examples
XML of the visits of the last 10 days, one entry per day https://demo.matomo.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 https://demo.matomo.org/?module=API&method=Referrers.getKeywords&idSite=3&period=week&date=last3&format=xml
XML containing the keywords from the last 3 days which match the pattern "piwik" https://demo.matomo.org/?module=API&method=Referrers.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 https://demo.matomo.org/?module=API&method=Referrers.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, such as: adding Annotations, creating custom Segments,