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>Sunday 21 September 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-08-23,2014-09-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>11</nb_visits>
			<nb_actions>37</nb_actions>
			<nb_actions_per_visit>3.36</nb_actions_per_visit>
			<avg_time_on_site>00:06:44</avg_time_on_site>
			<bounce_rate>45.45%</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>5</nb_actions>
			<nb_actions_per_visit>1.67</nb_actions_per_visit>
			<avg_time_on_site>00:00:18</avg_time_on_site>
			<bounce_rate>66.67%</bounce_rate>
			<revenue>$ 0</revenue>
		</row>
		<row>
			<label>Brazil</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>Germany</label>
			<nb_uniq_visitors>1</nb_uniq_visitors>
			<nb_visits>1</nb_visits>
			<nb_actions>2</nb_actions>
			<nb_actions_per_visit>2</nb_actions_per_visit>
			<avg_time_on_site>00:00:08</avg_time_on_site>
			<bounce_rate>0%</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>5</nb_uniq_visitors>
			<nb_visits>5</nb_visits>
			<nb_actions>6</nb_actions>
			<nb_actions_per_visit>1.2</nb_actions_per_visit>
			<avg_time_on_site>00:00:22</avg_time_on_site>
			<bounce_rate>80%</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>us</code>
			<logo>plugins/UserCountry/images/flags/us.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>br</code>
			<logo>plugins/UserCountry/images/flags/br.png</logo>
			<logoWidth>16</logoWidth>
			<logoHeight>11</logoHeight>
		</row>
		<row>
			<code>de</code>
			<logo>plugins/UserCountry/images/flags/de.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>23</nb_visits>
		<nb_uniq_visitors>21</nb_uniq_visitors>
		<nb_actions>53</nb_actions>
		<nb_visits_converted>0</nb_visits_converted>
		<bounce_count>14</bounce_count>
	</reportTotal>
	<timerMillis>72</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: