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


  • 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:


  • the website id


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


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


    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,yesterday

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


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


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:

Other examples

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,