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:

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>Thursday 31 July 2014</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&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-07-02,2014-07-31</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>6</nb_uniq_visitors>
			<nb_visits>6</nb_visits>
			<nb_actions>14</nb_actions>
			<nb_actions_per_visit>2.33</nb_actions_per_visit>
			<avg_time_on_site>00:02:04</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Indonesia</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:08</avg_time_on_site>
			<bounce_rate>50%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Russian Federation</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>Argentina</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>United Kingdom</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>4</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>
	</reportData>
	<reportMetadata>
		<row>
			<code>us</code>
			<logo>plugins/UserCountry/images/flags/us.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>ru</code>
			<logo>plugins/UserCountry/images/flags/ru.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>ar</code>
			<logo>plugins/UserCountry/images/flags/ar.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>gb</code>
			<logo>plugins/UserCountry/images/flags/gb.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
	</reportMetadata>
	<reportTotal>
		<nb_visits>16</nb_visits>
		<nb_uniq_visitors>16</nb_uniq_visitors>
		<nb_actions>25</nb_actions>
		<nb_visits_converted>0</nb_visits_converted>
		<bounce_count>12</bounce_count>
	</reportTotal>
	<timerMillis>67</timerMillis>
</result>

List and Definition of 'metadata' Response Attributes

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.

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.

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

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

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

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

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

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: