Report Metadata API Methods

The standard 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:

  • return the report category, name, but also name of all the columns (in a specific language), or the translated date label (eg. "Thursday 10 February 2011")
  • return the data units as well, including the % sign, money symbols like $ or €, or time format "00:04:17"
  • return the processed metrics (ratios, averages) that are not returned in the normal API response, for example: bounce rate and time on site. The Piwik Metadata API provides a simple entry point to get this additional information for most Piwik API functions returning analytics data.

Fetch the Analytics Data and Metadata for a report

The method API.getProcessedReport can be called to request the full data set (metadata, column names, report data) of a given Piwik report. The response contains:

The returned XML is:

<?xml version="1.0" encoding="utf-8" ?>
<result>
	<website>virtual-drums.com</website>
	<prettyDate>Sunday 21 December 2014</prettyDate>
	<metadata>
		<category>Visitors</category>
		<name>Country</name>
		<module>UserCountry</module>
		<action>getCountry</action>
		<dimension>Country</dimension>
		<documentation>This report shows which country your visitors were in when they accessed 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 he visits a page more than 30 minutes after his 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 he visits 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>
		</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>
		<metricsGoal>
			<nb_conversions>Conversions</nb_conversions>
			<revenue>Revenue</revenue>
		</metricsGoal>
		<processedMetricsGoal>
			<revenue_per_visit>Revenue per Visit</revenue_per_visit>
		</processedMetricsGoal>
		<imageGraphUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=UserCountry&amp;apiAction=getCountry&amp;token_auth=anonymous&amp;period=day&amp;date=yesterday</imageGraphUrl>
		<imageGraphEvolutionUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=UserCountry&amp;apiAction=getCountry&amp;token_auth=anonymous&amp;period=day&amp;date=2014-11-22,2014-12-21</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>Philippines</label>
			<nb_uniq_visitors>9</nb_uniq_visitors>
			<nb_visits>9</nb_visits>
			<nb_actions>32</nb_actions>
			<nb_actions_per_visit>3.6</nb_actions_per_visit>
			<avg_time_on_site>00:01:10</avg_time_on_site>
			<bounce_rate>67%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Belgium</label>
			<nb_uniq_visitors>5</nb_uniq_visitors>
			<nb_visits>8</nb_visits>
			<nb_actions>20</nb_actions>
			<nb_actions_per_visit>2.5</nb_actions_per_visit>
			<avg_time_on_site>00:03:19</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Indonesia</label>
			<nb_uniq_visitors>3</nb_uniq_visitors>
			<nb_visits>3</nb_visits>
			<nb_actions>3</nb_actions>
			<nb_actions_per_visit>1</nb_actions_per_visit>
			<avg_time_on_site>00:00:00</avg_time_on_site>
			<bounce_rate>100%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>United States</label>
			<nb_uniq_visitors>3</nb_uniq_visitors>
			<nb_visits>3</nb_visits>
			<nb_actions>3</nb_actions>
			<nb_actions_per_visit>1</nb_actions_per_visit>
			<avg_time_on_site>00:00:00</avg_time_on_site>
			<bounce_rate>100%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Egypt</label>
			<nb_uniq_visitors>1</nb_uniq_visitors>
			<nb_visits>1</nb_visits>
			<nb_actions>1</nb_actions>
			<nb_actions_per_visit>1</nb_actions_per_visit>
			<avg_time_on_site>00:00:00</avg_time_on_site>
			<bounce_rate>100%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Others</label>
			<nb_uniq_visitors>4</nb_uniq_visitors>
			<nb_visits>4</nb_visits>
			<nb_actions>10</nb_actions>
			<nb_actions_per_visit>2.5</nb_actions_per_visit>
			<avg_time_on_site>00:00:22</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
	</reportData>
	<reportMetadata>
		<row>
			<code>ph</code>
			<logo>plugins/UserCountry/images/flags/ph.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>be</code>
			<logo>plugins/UserCountry/images/flags/be.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>id</code>
			<logo>plugins/UserCountry/images/flags/id.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>us</code>
			<logo>plugins/UserCountry/images/flags/us.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>eg</code>
			<logo>plugins/UserCountry/images/flags/eg.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
	</reportMetadata>
	<reportTotal>
		<nb_visits>28</nb_visits>
		<nb_uniq_visitors>25</nb_uniq_visitors>
		<nb_actions>69</nb_actions>
		<nb_visits_converted>0</nb_visits_converted>
		<bounce_count>19</bounce_count>
	</reportTotal>
	<timerMillis>49</timerMillis>
</result>

List and Definition of 'metadata' Response Attributes

  • category - category under which the report appears
  • name - the report name
  • module and 'action' - used to build the standard API request to fetch the data for this report, ?module=API&method=$module.$action (replace $module by the 'module' attribute, replace $action by the 'action' attribute)
  • metrics - list of basic metrics in the report
  • processedMetrics - list of processed metrics in the report. Processed metrics are usually ratios (conversion rates, average actions per visit, etc.). Processed metrics don't appear in standard non-metadata API responses.
  • metricsGoal and 'processedMetricsGoal' - list of goal metrics available for this report.
  • uniqueId - the report unique ID.
  • constantRowsCount - if set to 1, this means that the report always has the same number of rows. For example, "visits per hour" always has 24 hours, "visits per number of pages" has 10 rows. This attribute is set only when there is a 'dimension' attribute. If this attribute is not set, it means that the returned data set could have 0 row, 1 row, or N rows.

Listing all the Metadata API Functions

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 Piwik demo.

There are two types of reports in Piwik, 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>Visits Summary</category>
    		<name>Visits Summary</name>
    		<module>VisitsSummary</module>
    		<action>get</action>
    		<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 he visits the website multiple times a day.</nb_uniq_visitors>
    			<nb_visits>If a visitor comes to your website for the first time or if he visits a page more than 30 minutes after his 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>
    		<imageGraphUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=VisitsSummary&amp;apiAction=get&amp;token_auth=anonymous&amp;period=day&amp;date=2014-11-23,2014-12-22</imageGraphUrl>
    		<imageGraphEvolutionUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=VisitsSummary&amp;apiAction=get&amp;token_auth=anonymous&amp;period=day&amp;date=2014-11-23,2014-12-22</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>
    		<name>Keywords</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. &lt;br /&gt; By clicking on a row in the table, you can see the distribution of search engines that were queried for the keyword.</documentation>
    		<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 he visits a page more than 30 minutes after his 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 he visits 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>
    		</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>
    		<actionToLoadSubTables>getSearchEnginesFromKeywordId</actionToLoadSubTables>
    		<metricsGoal>
    			<nb_conversions>Conversions</nb_conversions>
    			<revenue>Revenue</revenue>
    		</metricsGoal>
    		<processedMetricsGoal>
    			<revenue_per_visit>Revenue per Visit</revenue_per_visit>
    		</processedMetricsGoal>
    		<imageGraphUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=Referrers&amp;apiAction=getKeywords&amp;token_auth=anonymous&amp;period=day&amp;date=today</imageGraphUrl>
    		<imageGraphEvolutionUrl>index.php?module=API&amp;method=ImageGraph.get&amp;idSite=3&amp;apiModule=Referrers&amp;apiAction=getKeywords&amp;token_auth=anonymous&amp;period=day&amp;date=2014-11-23,2014-12-22</imageGraphEvolutionUrl>
    		<uniqueId>Referrers_getKeywords</uniqueId>
    	</row>
    </result>
    

Static Image Graphs

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 Piwik 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 Piwik 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=3&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=3&apiModule=UserSettings&apiAction=getBrowser&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=3&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=3&apiModule=UserSettings&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=7&apiModule=UserSettings&apiAction=getOS&token_auth=anonymous&graphType=pie&period=month&date=today&width=500&height=250&column=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=7&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 Piwik parameters (idSite, date, period, etc.) but also accepts the following parameters:

  • graphType - defines the type of graph to draw. Accepted values are: 'evolution' (line graph), 'horizontalBar' (horizontal bar graph), 'verticalBar' (vertical bar graph) and 'pie' (2D Pie chart)
  • width and height - define the width and height in pixels of the generated image
  • column - by default, the graph will plot the number of visits (nb_visits). You can specify another metric such as: nb_actions, nb_visits_converted, nb_uniq_visitors, etc.
  • colors - you can specify a comma separated list of hexadecimal colors to use in the graph instead of the default colors, eg. &colors=FFFF00,00FF00,FF0000
  • aliasedGraph - by default, graphs are "smooth" (anti-aliased). If you are generating hundreds of graphs and are concerned with performance, you can set aliasedGraph=0. This will disable anti-aliasing and graphs will be generated faster, but won't look so pretty.