Metadata API

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:

‘metadata’ – report name, category, list of metrics
‘columns’ – the list of translated column names in the report
‘reportData’ – the actual data: dimension and list of metrics
‘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
Truncated to 5 rows: &filter_truncate=5
Labels can be translated into a specific language. As with other API calls, you can use the parameter &language=xx (replacing xx with the translation code).

The URL would be http://demo.piwik.org/?module=API&method=API.getProcessedReport&idSite=3&date=yesterday&period=day&apiModule=UserCountry&apiAction=getCountry&language=en&format=xml&token_auth=anonymous&filter_truncate=5

The returned XML is:

<?xml version="1.0" encoding="utf-8" ?>
<result>
	<website>virtual-drums.com</website>
	<prettyDate>Saturday 18 May 2013</prettyDate>
	<metadata>
		<category>Visitors</category>
		<name>Country</name>
		<module>UserCountry</module>
		<action>getCountry</action>
		<dimension>Country</dimension>
		<metrics>
			<nb_visits>Visits</nb_visits>
			<nb_uniq_visitors>Unique visitors</nb_uniq_visitors>
			<nb_actions>Actions</nb_actions>
		</metrics>
		<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>
		<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_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>
			<avg_time_on_page>The average amount of time visitors spent on this page (only the page, not the entire website).</avg_time_on_page>
			<nb_hits>The number of times this page was visited.</nb_hits>
			<exit_rate>The percentage of visits that left the website after viewing this page.</exit_rate>
		</metricsDocumentation>
		<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&method=ImageGraph.get&idSite=3&apiModule=UserCountry&apiAction=getCountry&token_auth=anonymous&period=day&date=yesterday</imageGraphUrl>
		<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=3&apiModule=UserCountry&apiAction=getCountry&token_auth=anonymous&period=day&date=2013-04-19,2013-05-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>13</nb_uniq_visitors>
			<nb_visits>13</nb_visits>
			<nb_actions>22</nb_actions>
			<nb_actions_per_visit>1.69</nb_actions_per_visit>
			<avg_time_on_site>00:01:02</avg_time_on_site>
			<bounce_rate>61.54%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>France</label>
			<nb_uniq_visitors>2</nb_uniq_visitors>
			<nb_visits>2</nb_visits>
			<nb_actions>2</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 Kingdom</label>
			<nb_uniq_visitors>2</nb_uniq_visitors>
			<nb_visits>2</nb_visits>
			<nb_actions>2</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>Mexico</label>
			<nb_uniq_visitors>2</nb_uniq_visitors>
			<nb_visits>2</nb_visits>
			<nb_actions>3</nb_actions>
			<nb_actions_per_visit>1.5</nb_actions_per_visit>
			<avg_time_on_site>00:00:24</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Philippines</label>
			<nb_uniq_visitors>2</nb_uniq_visitors>
			<nb_visits>2</nb_visits>
			<nb_actions>5</nb_actions>
			<nb_actions_per_visit>2.5</nb_actions_per_visit>
			<avg_time_on_site>00:00:30</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Others</label>
			<nb_uniq_visitors>15</nb_uniq_visitors>
			<nb_visits>15</nb_visits>
			<nb_actions>19</nb_actions>
			<nb_actions_per_visit>1.27</nb_actions_per_visit>
			<avg_time_on_site>00:00:08</avg_time_on_site>
			<bounce_rate>73.33%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
	</reportData>
	<reportMetadata>
		<row>
			<code>us</code>
			<logo>plugins/UserCountry/flags/us.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>fr</code>
			<logo>plugins/UserCountry/flags/fr.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>gb</code>
			<logo>plugins/UserCountry/flags/gb.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>mx</code>
			<logo>plugins/UserCountry/flags/mx.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>ph</code>
			<logo>plugins/UserCountry/flags/ph.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
	</reportMetadata>
	<timerMillis>40</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_actions>Actions</nb_actions>
			<nb_actions_per_visit>Actions per Visit</nb_actions_per_visit>
			<bounce_rate>Bounce Rate</bounce_rate>
			<avg_time_on_site>Avg. Visit Duration (in seconds)</avg_time_on_site>
			<max_actions>Maximum actions in one visit</max_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>
			<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>
			<avg_time_on_page>The average amount of time visitors spent on this page (only the page, not the entire website).</avg_time_on_page>
			<nb_hits>The number of times this page was visited.</nb_hits>
			<exit_rate>The percentage of visits that left the website after viewing this page.</exit_rate>
		</metricsDocumentation>
		<imageGraphUrl>index.php?module=API&method=ImageGraph.get&idSite=3&apiModule=VisitsSummary&apiAction=get&token_auth=anonymous&period=day&date=2013-04-20,2013-05-19</imageGraphUrl>
		<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=3&apiModule=VisitsSummary&apiAction=get&token_auth=anonymous&period=day&date=2013-04-20,2013-05-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>
		<name>Keywords</name>
		<module>Referers</module>
		<action>getKeywords</action>
		<actionToLoadSubTables>getSearchEnginesFromKeywordId</actionToLoadSubTables>
		<dimension>Keyword</dimension>
		<documentation>This report shows which keywords users were searching for before they were referred to your website. <br /> 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>
		</metrics>
		<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>
		<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_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>
			<avg_time_on_page>The average amount of time visitors spent on this page (only the page, not the entire website).</avg_time_on_page>
			<nb_hits>The number of times this page was visited.</nb_hits>
			<exit_rate>The percentage of visits that left the website after viewing this page.</exit_rate>
		</metricsDocumentation>
		<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&method=ImageGraph.get&idSite=3&apiModule=Referers&apiAction=getKeywords&token_auth=anonymous&period=day&date=today</imageGraphUrl>
		<imageGraphEvolutionUrl>index.php?module=API&method=ImageGraph.get&idSite=3&apiModule=Referers&apiAction=getKeywords&token_auth=anonymous&period=day&date=2013-04-20,2013-05-19</imageGraphEvolutionUrl>
		<uniqueId>Referers_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=UserSettings&apiAction=getResolution&token_auth=anonymous&graphType=verticalBar&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

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

Fetch the Analytics Data and Metadata for a report

List and Definition of ‘metadata’ Response Attributes

Listing all the Metadata API Functions

Static Image Graphs

Feedback on this page

Piwik

Features

Community

About

Help

Social