The standard Matomo (formerly Piwik) Analytics APIs return raw data, for example: visits, page views, revenue, conversions.
The Metadata API is the service that calls other APIs, then add more metadata around it, for example, it will:
The method API.getProcessedReport can be called to request the full data set (metadata, column names, report data) of a given Matomo report. The response contains:
'reportMetadata' - (optional) contains the metadata for each row, for example: logo URLs, country codes, search engine URLs, etc. For example, if you want to display the top five countries that visitors come from you would build the API Request as follows:
User countries report: &apiModule=UserCountry&apiAction=getCountry
&filter_truncate=5&language=xx (replacing xx with the translation code).
The URL would be https://demo.matomo.cloud/?module=API&method=API.getProcessedReport&idSite=1&date=yesterday&period=day&apiModule=UserCountry&apiAction=getCountry&language=en&format=xml&token_auth=anonymous&filter_truncate=5The returned XML is:
<?xml version="1.0" encoding="utf-8" ?>
<result>
<website>Demo Site</website>
<prettyDate>Monday, November 18, 2024</prettyDate>
<metadata>
<category>Visitors</category>
<subcategory>Locations</subcategory>
<name>Country</name>
<module>UserCountry</module>
<action>getCountry</action>
<dimension>Country</dimension>
<documentation>Shows which country your visitors connected from when accessing your website.</documentation>
<metrics>
<nb_visits>Visits</nb_visits>
<nb_uniq_visitors>Unique visitors</nb_uniq_visitors>
<nb_actions>Actions</nb_actions>
</metrics>
<metricsDocumentation>
<nb_visits>If a visitor comes to your website for the first time or if they visit a page more than 30 minutes after their last page view, this will be recorded as a new visit.</nb_visits>
<nb_uniq_visitors>The number of unduplicated visitors coming to your website. Every user is only counted once, even if they visit the website multiple times a day.</nb_uniq_visitors>
<nb_actions>The number of actions performed by your visitors. Actions can be page views, internal site searches, downloads or outlinks.</nb_actions>
<nb_actions_per_visit>The average number of actions (page views, site searches, downloads or outlinks) that were performed during the visits.</nb_actions_per_visit>
<avg_time_on_site>The average duration of a visit.</avg_time_on_site>
<bounce_rate>The percentage of visits that only had a single pageview. This means, that the visitor left the website directly from the entrance page.</bounce_rate>
<conversion_rate>The percentage of visits that triggered a goal conversion.</conversion_rate>
</metricsDocumentation>
<processedMetrics>
<nb_actions_per_visit>Actions per Visit</nb_actions_per_visit>
<avg_time_on_site>Avg. Time on Website</avg_time_on_site>
<bounce_rate>Bounce Rate</bounce_rate>
</processedMetrics>
<metricTypes>
<nb_visits>number</nb_visits>
<nb_uniq_visitors>number</nb_uniq_visitors>
<nb_actions>number</nb_actions>
<nb_actions_per_visit>number</nb_actions_per_visit>
<avg_time_on_site>duration_s</avg_time_on_site>
<bounce_rate>percent</bounce_rate>
<conversion_rate>percent</conversion_rate>
</metricTypes>
<metricsGoal>
<nb_conversions>Conversions</nb_conversions>
<revenue>Revenue</revenue>
</metricsGoal>
<processedMetricsGoal>
<revenue_per_visit>Revenue per Visit</revenue_per_visit>
</processedMetricsGoal>
<metricTypesGoal>
<revenue_per_visit>money</revenue_per_visit>
<nb_conversions>number</nb_conversions>
<conversion_rate>percent</conversion_rate>
<revenue>money</revenue>
</metricTypesGoal>
<imageGraphUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=UserCountry&apiAction=getCountry&token_auth=anonymous&period=day&date=yesterday</imageGraphUrl>
<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=UserCountry&apiAction=getCountry&token_auth=anonymous&period=day&date=2024-10-20,2024-11-18</imageGraphEvolutionUrl>
<uniqueId>UserCountry_getCountry</uniqueId>
</metadata>
<columns>
<label>Country</label>
<nb_visits>Visits</nb_visits>
<nb_uniq_visitors>Unique visitors</nb_uniq_visitors>
<nb_actions>Actions</nb_actions>
<nb_actions_per_visit>Actions per Visit</nb_actions_per_visit>
<avg_time_on_site>Avg. Time on Website</avg_time_on_site>
<bounce_rate>Bounce Rate</bounce_rate>
<revenue>Revenue</revenue>
</columns>
<reportData>
<row>
<label>United States</label>
<nb_uniq_visitors>1844</nb_uniq_visitors>
<nb_visits>1972</nb_visits>
<nb_actions>5175</nb_actions>
<revenue>$10,674.60</revenue>
<nb_actions_per_visit>2.6</nb_actions_per_visit>
<avg_time_on_site>00:03:42</avg_time_on_site>
<bounce_rate>62%</bounce_rate>
</row>
<row>
<label>Australia</label>
<nb_uniq_visitors>887</nb_uniq_visitors>
<nb_visits>963</nb_visits>
<nb_actions>2066</nb_actions>
<revenue>$4,735.50</revenue>
<nb_actions_per_visit>2.1</nb_actions_per_visit>
<avg_time_on_site>00:02:41</avg_time_on_site>
<bounce_rate>64%</bounce_rate>
</row>
<row>
<label>United Kingdom</label>
<nb_uniq_visitors>754</nb_uniq_visitors>
<nb_visits>791</nb_visits>
<nb_actions>1874</nb_actions>
<revenue>$2,062.65</revenue>
<nb_actions_per_visit>2.4</nb_actions_per_visit>
<avg_time_on_site>00:02:45</avg_time_on_site>
<bounce_rate>61%</bounce_rate>
</row>
<row>
<label>Indonesia</label>
<nb_uniq_visitors>610</nb_uniq_visitors>
<nb_visits>658</nb_visits>
<nb_actions>1337</nb_actions>
<revenue>$391.60</revenue>
<nb_actions_per_visit>2</nb_actions_per_visit>
<avg_time_on_site>00:02:14</avg_time_on_site>
<bounce_rate>68%</bounce_rate>
</row>
<row>
<label>Germany</label>
<nb_uniq_visitors>478</nb_uniq_visitors>
<nb_visits>554</nb_visits>
<nb_actions>3393</nb_actions>
<revenue>$16,086.15</revenue>
<nb_actions_per_visit>6.1</nb_actions_per_visit>
<avg_time_on_site>00:11:48</avg_time_on_site>
<bounce_rate>27%</bounce_rate>
</row>
<row>
<label>Others</label>
<nb_uniq_visitors>5119</nb_uniq_visitors>
<nb_visits>5593</nb_visits>
<nb_actions>16517</nb_actions>
<revenue>$38,085.50</revenue>
<nb_actions_per_visit>3</nb_actions_per_visit>
<avg_time_on_site>00:04:19</avg_time_on_site>
<bounce_rate>59%</bounce_rate>
</row>
</reportData>
<reportMetadata>
<row>
<code>us</code>
<logo>plugins/Morpheus/icons/dist/flags/us.png</logo>
<segment>countryCode==us</segment>
<logoHeight>16</logoHeight>
</row>
<row>
<code>au</code>
<logo>plugins/Morpheus/icons/dist/flags/au.png</logo>
<segment>countryCode==au</segment>
<logoHeight>16</logoHeight>
</row>
<row>
<code>gb</code>
<logo>plugins/Morpheus/icons/dist/flags/gb.png</logo>
<segment>countryCode==gb</segment>
<logoHeight>16</logoHeight>
</row>
<row>
<code>id</code>
<logo>plugins/Morpheus/icons/dist/flags/id.png</logo>
<segment>countryCode==id</segment>
<logoHeight>16</logoHeight>
</row>
<row>
<code>de</code>
<logo>plugins/Morpheus/icons/dist/flags/de.png</logo>
<segment>countryCode==de</segment>
<logoHeight>16</logoHeight>
</row>
<row>
<logoHeight>16</logoHeight>
</row>
</reportMetadata>
<reportTotal>
<nb_uniq_visitors>9692</nb_uniq_visitors>
<nb_visits>10531</nb_visits>
<nb_actions>30362</nb_actions>
<nb_users>6</nb_users>
<max_actions>80</max_actions>
<sum_visit_length>2650743</sum_visit_length>
<bounce_count>6197</bounce_count>
<nb_visits_converted>951</nb_visits_converted>
<goals>
<row idgoal="ecommerceAbandonedCart">
<nb_conversions>971</nb_conversions>
<nb_visits_converted>971</nb_visits_converted>
<revenue>207935.5</revenue>
<items>1413</items>
</row>
<row idgoal="ecommerceOrder">
<nb_conversions>356</nb_conversions>
<nb_visits_converted>344</nb_visits_converted>
<revenue>71495</revenue>
<revenue_subtotal>93666.88</revenue_subtotal>
<revenue_tax>2016.53</revenue_tax>
<revenue_shipping>0</revenue_shipping>
<revenue_discount>9498.17</revenue_discount>
<items>485</items>
</row>
<row idgoal="4">
<nb_conversions>16</nb_conversions>
<nb_visits_converted>16</nb_visits_converted>
<revenue>16</revenue>
</row>
<row idgoal="5">
<nb_conversions>15</nb_conversions>
<nb_visits_converted>15</nb_visits_converted>
<revenue>75</revenue>
</row>
<row idgoal="6">
<nb_conversions>28</nb_conversions>
<nb_visits_converted>28</nb_visits_converted>
<revenue>56</revenue>
</row>
<row idgoal="7">
<nb_conversions>394</nb_conversions>
<nb_visits_converted>394</nb_visits_converted>
<revenue>394</revenue>
</row>
<row idgoal="8">
<nb_conversions>168</nb_conversions>
<nb_visits_converted>168</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal="9">
<nb_conversions>8</nb_conversions>
<nb_visits_converted>5</nb_visits_converted>
<revenue>0</revenue>
</row>
<row idgoal="10">
<nb_conversions>8</nb_conversions>
<nb_visits_converted>8</nb_visits_converted>
<revenue>0</revenue>
</row>
</goals>
<nb_conversions>993</nb_conversions>
<revenue>72036</revenue>
<nb_actions_per_visit>2.9</nb_actions_per_visit>
</reportTotal>
<timerMillis>126</timerMillis>
</result>
?module=API&method=$module.$action (replace $module by the 'module' attribute, replace $action by the 'action' attribute)The API method API.getReportMetadata can be called to request the full list of API functions returning web analytics reports - see the example output on the Matomo demo.
There are two types of reports in Matomo, and each have a slightly different format.
Simple metrics reports
Simple Metrics reports simply contain a list of metrics and their values. For example, VisitsSummary.get returns the main metrics (visits, pages, unique visitors) for the specified website (example URL).
<?xml version="1.0" encoding="utf-8" ?>
<result>
<row>
<category>Visitors</category>
<subcategory>Overview</subcategory>
<name>Visits Summary</name>
<module>VisitsSummary</module>
<action>get</action>
<documentation>This report provides a very general overview of how your visitors behave.</documentation>
<metrics>
<nb_uniq_visitors>Unique visitors</nb_uniq_visitors>
<nb_visits>Visits</nb_visits>
<nb_users>Users</nb_users>
<nb_actions>Actions</nb_actions>
<max_actions>Maximum actions in one visit</max_actions>
</metrics>
<metricsDocumentation>
<nb_uniq_visitors>The number of unduplicated visitors coming to your website. Every user is only counted once, even if they visit the website multiple times a day.</nb_uniq_visitors>
<nb_visits>If a visitor comes to your website for the first time or if they visit a page more than 30 minutes after their last page view, this will be recorded as a new visit.</nb_visits>
<nb_users>The number of users logged in your website. It is the number of unique active users that have a User ID set (via the Tracking code function 'setUserId').</nb_users>
<nb_actions>The number of actions performed by your visitors. Actions can be page views, internal site searches, downloads or outlinks.</nb_actions>
<bounce_rate>The percentage of visits that only had a single pageview. This means, that the visitor left the website directly from the entrance page.</bounce_rate>
<nb_actions_per_visit>The average number of actions (page views, site searches, downloads or outlinks) that were performed during the visits.</nb_actions_per_visit>
<avg_time_on_site>The average duration of a visit.</avg_time_on_site>
</metricsDocumentation>
<processedMetrics>
<bounce_rate>Bounce Rate</bounce_rate>
<nb_actions_per_visit>Actions per Visit</nb_actions_per_visit>
<avg_time_on_site>Avg. Visit Duration (in seconds)</avg_time_on_site>
</processedMetrics>
<metricTypes>
<nb_uniq_visitors>number</nb_uniq_visitors>
<nb_visits>number</nb_visits>
<nb_users>number</nb_users>
<nb_actions>number</nb_actions>
<max_actions>number</max_actions>
<bounce_rate>percent</bounce_rate>
<nb_actions_per_visit>number</nb_actions_per_visit>
<avg_time_on_site>duration_s</avg_time_on_site>
</metricTypes>
<imageGraphUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=VisitsSummary&apiAction=get&token_auth=anonymous&period=day&date=2024-10-21,2024-11-19</imageGraphUrl>
<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=VisitsSummary&apiAction=get&token_auth=anonymous&period=day&date=2024-10-21,2024-11-19</imageGraphEvolutionUrl>
<uniqueId>VisitsSummary_get</uniqueId>
</row>
</result>
Reports with dimensions
Most reports, however, will have a 'dimension' entry in the returned array. Reports with dimensions will display a list of metrics for each 'dimension'. For example, the list of visits, pages, time on site will be output for each keyword.
Example of a report with dimensions metadata (example URL):
<?xml version="1.0" encoding="utf-8" ?>
<result>
<row>
<category>Referrers</category>
<subcategory>Search Engines & Keywords</subcategory>
<name>Keywords (including not defined)</name>
<module>Referrers</module>
<action>getKeywords</action>
<dimension>Keyword</dimension>
<documentation>This report shows which keywords users were searching for before they were referred to your website. <br /><br /> By clicking on a row in the table, you can see the distribution of search engines that were queried for the keyword.<br /><br />Note: This report lists most keywords as not defined, because most search engines do not send the exact keyword used on the search engine.</documentation>
<dimensions>
<Referrers_Keyword>Keyword</Referrers_Keyword>
<Referrers_SearchEngine>Search Engine</Referrers_SearchEngine>
</dimensions>
<metrics>
<nb_visits>Visits</nb_visits>
<nb_uniq_visitors>Unique visitors</nb_uniq_visitors>
<nb_actions>Actions</nb_actions>
<nb_users>Users</nb_users>
</metrics>
<metricsDocumentation>
<nb_visits>If a visitor comes to your website for the first time or if they visit a page more than 30 minutes after their last page view, this will be recorded as a new visit.</nb_visits>
<nb_uniq_visitors>The number of unduplicated visitors coming to your website. Every user is only counted once, even if they visit the website multiple times a day.</nb_uniq_visitors>
<nb_actions>The number of actions performed by your visitors. Actions can be page views, internal site searches, downloads or outlinks.</nb_actions>
<nb_users>The number of users logged in your website. It is the number of unique active users that have a User ID set (via the Tracking code function 'setUserId').</nb_users>
<nb_actions_per_visit>The average number of actions (page views, site searches, downloads or outlinks) that were performed during the visits.</nb_actions_per_visit>
<avg_time_on_site>The average duration of a visit.</avg_time_on_site>
<bounce_rate>The percentage of visits that only had a single pageview. This means, that the visitor left the website directly from the entrance page.</bounce_rate>
<conversion_rate>The percentage of visits that triggered a goal conversion.</conversion_rate>
</metricsDocumentation>
<processedMetrics>
<nb_actions_per_visit>Actions per Visit</nb_actions_per_visit>
<avg_time_on_site>Avg. Time on Website</avg_time_on_site>
<bounce_rate>Bounce Rate</bounce_rate>
</processedMetrics>
<metricTypes>
<nb_visits>number</nb_visits>
<nb_uniq_visitors>number</nb_uniq_visitors>
<nb_actions>number</nb_actions>
<nb_users>number</nb_users>
<nb_actions_per_visit>number</nb_actions_per_visit>
<avg_time_on_site>duration_s</avg_time_on_site>
<bounce_rate>percent</bounce_rate>
<conversion_rate>percent</conversion_rate>
</metricTypes>
<actionToLoadSubTables>getSearchEnginesFromKeywordId</actionToLoadSubTables>
<relatedReports>
<row>
<name>Combined imported keywords</name>
<module>SearchEngineKeywordsPerformance</module>
<action>getKeywordsImported</action>
</row>
<row>
<name>Combined keywords</name>
<module>SearchEngineKeywordsPerformance</module>
<action>getKeywords</action>
</row>
</relatedReports>
<metricsGoal>
<nb_conversions>Conversions</nb_conversions>
<revenue>Revenue</revenue>
</metricsGoal>
<processedMetricsGoal>
<revenue_per_visit>Revenue per Visit</revenue_per_visit>
</processedMetricsGoal>
<metricTypesGoal>
<revenue_per_visit>money</revenue_per_visit>
<nb_conversions>number</nb_conversions>
<conversion_rate>percent</conversion_rate>
<revenue>money</revenue>
</metricTypesGoal>
<imageGraphUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=Referrers&apiAction=getKeywords&token_auth=anonymous&period=day&date=today</imageGraphUrl>
<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=Referrers&apiAction=getKeywords&token_auth=anonymous&period=day&date=2024-10-21,2024-11-19</imageGraphEvolutionUrl>
<uniqueId>Referrers_getKeywords</uniqueId>
</row>
</result>
In the metadata output, the field <imageGraphUrl> is a URL that will generate a static PNG graph plotting data for the requested report. Static PNG graphs are used, for example, in the Matomo mobile app and in email reports. These static image graphs can also be used in any custom dashboard, web page, monitoring page, email, etc. As opposed to the Matomo Widgets, static image graphs do not require JavaScript or HTML, since the URL returns a PNG image.
In the following examples, to see the URL used to generate the image, right-click on the image and select "view image" to see the full URL.
Example: Graph Plotting Visits over the Last 30 Days
URL: index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=VisitsSummary&apiAction=get&token_auth=anonymous&graphType=evolution&period=day&date=previous30&width=500&height=250
Example: Horizontal Bar Graph Plotting Browsers for the Current Month
URL: index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=DevicesDetection&apiAction=getBrowsers&token_auth=anonymous&graphType=horizontalBar&period=month&date=today&width=500&height=250
Example: Horizontal Bar Graph Plotting Countries for the Current Week
URL: index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=UserCountry&apiAction=getCountry&token_auth=anonymous&graphType=horizontalBar&period=month&date=today&width=500&height=250
Example: Graph Plotting User Screen Resolutions for the Current Month
URL: index.php?module=API&method=ImageGraph.get&idSite=1&apiModule=Resolution&apiAction=getResolution&token_auth=anonymous&graphType=verticalBar&period=month&date=today&width=500&height=250
Example: Pie Chart with Custom Colors
URL: index.php?module=API&method=ImageGraph.get&idSite=62&apiModule=DevicesDetection&apiAction=getOsVersions&token_auth=anonymous&graphType=pie&period=month&date=today&width=500&height=250&columns=nb_visits&colors=FFFF00,00FF00,FF0000,0000FF,555555,C3590D
Example: Line chart of Custom Variables names and values, filtered to show only custom variable containing the string "logged"
URL: index.php?module=API&method=ImageGraph.get&idSite=62&apiModule=CustomVariables&apiAction=getCustomVariables&token_auth=anonymous&period=day&date=2013-11-11,2013-11-18&flat=1&filter_pattern_recursive=.*logged.*
The static Graphs API requires the standard Matomo parameters (idSite, date, period, etc.) but also accepts the following parameters: