June 12, 2018
The document below outlines key concepts of the API including functions, documents, and parameters that you can play with. Feel free to pull all your relevant data from Piwik PRO into your custom apps, like reporting dashboards, BI software, data warehouses, etc.
A request to the Piwik PRO Reporting API is composed of standard and additional API parameters.
Standard API Parameters
An array containing integer id(s) of your website or websites
The period you request the statistics for: can be a day, week, month, year, or range. All reports are returned for the dates based on the website’s time zone.
Example: to request a report for the range Jan 1st to Jan 31th you would write &period=range&date=2017-01-01,2017-01-31
A reference to a specific date comes in standard format = YYYY-MM-DD but can be used with “magic keywords” like today or yesterday. These are relative to the website timezone.
Example: for a website with UTC+12 timezone, “date=today” for an API request at 5PM UTC on 2017-01-01 will return the reports for 2017-01-02.
range of date
Refers to the last or previous amount of periods from the actual date, including today and is relative to the website timezone. Here are some examples of the syntax:
This returns an entry for each of the last 5 days including today.
This returns an entry for each of the 52 weeks before the current week.
This returns an entry of the sum of the data for the specified date range.
The “date” parameter supports the following special keywords:
This parameter refers to the Custom Segment of traffic you want to use to filter your Piwik PRO reports.
This returns the requested API report, processed for users coming just from facebook.com.
Logical operators are handled here with commas and semicolons, where comma means OR and semicolon means AND. To form an alternative clause you would write
Which Is equal to:
facebook.com OR twitter.com
To form a conjunction of alternatives, you would write:
Which is equivalent to the following:
(referrer facebook.com OR twitter.com) AND (referrer Google OR country US)
To check all available options, please refer to the segmentation documentation, where you will find a list of dimensions and metrics, example values for each and more information on the custom segment parameter.
Defines the format of the output of your API call, and may take one of the following values: