Read this guide if
This guide assumes that you:
Piwik's Reporting API allows third party applications to access analytics data and manipulate miscellaneous data (anything other than reports or tracked data) through HTTP requests.
Every HTTP API request to the
API.index controller method will be handled by the Reporting API. Valid requests must have a query parameter named
method that references the API method to invoke, for example,
API requests are processed in the following way:
API::index()controller method creates a
Piwik\API\Requestinstance and uses it to dispatch the API request.
Requestinstance uses the
methodquery parameter to determine which plugin and API method to use.
Requestinstance invokes the plugin's API method using query parameters as arguments. Query parameters with the same name as method parameters will be passed to the method. For example,
idSitequery parameter will be passed as the
Requestinstance uses a
ResponseBuilderinstance to process the result of the API method and convert it into the desired output format.
API::index()controller method and is sent as the HTTP response.
The Reporting API invokes methods that are found in each plugin's API class. However the following methods cannot be called from the HTTP API:
Query parameters are passed as method parameters. So API methods must assume method parameters will be string or array values. Objects are not allowed as parameters.
Methods are only allowed to return the following values:
If a method throws an exception its message will appear in the output. The stack trace can be displayed during debugging by changing
You can see the list of all API methods your Piwik install exposes: click the API link in the top menu. See the demo's list here.
A set of
DataTable\BaseFilter are executed on the reports based on the values of certain query parameters.
This is the list of filters in the order in which they are applied:
DataTablehierarchy into one
DataTable, adding rows of subtables to their parent rows.
flat: set to
1to apply the filter
DataTablethat do not match a regex pattern.
filter_pattern: regular expression (the filter is applied if set)
filter_column: column to apply the regex pattern to (
labelcolumn by default)
DataTablefor which the row and all subtables of the row do not match a regex pattern.
filter_pattern_recursive: regular expression (the filter is applied if set)
filter_column_recursive: column to apply the regex pattern to (
labelcolumn by default)
filter_excludelowpop: column to filter (the filter is applied if set)
filter_excludelowpop_value: minimum threshold value (defaults to
filter_add_columns_when_show_all_columns: set to
1to apply the filter
filter_update_columns_when_show_all_goals: set to
1to apply the filter
idGoal: ID of a goal or one of these special values:
AddColumnsProcessedMetricsGoal::GOALS_OVERVIEW(default): adds metrics for the goals overview and not individual goals
AddColumnsProcessedMetricsGoal::GOALS_MINIMAL_REPORT: add just one metric:
revenue_per_visit(no per-goal metrics will be added)
AddColumnsProcessedMetricsGoal::GOALS_FULL_TABLE: displays per-goal metrics for every goal of the site including the ecommerce goal
filter_sort_column: column to sort (the filter is applied if set)
filter_truncate: row number after which rows should be removed (the filter is applied if set)
filter_limit: size of the range (the filter is applied if set)
filter_offset: starting row index of the range
keep_summary_row: if set to
1, the summary row is kept in the report
labelcolumn values. This filter is always applied.
DataTable's queued filters are applied at this point.
disable_queued_filters: if set to
1, queued filters will not be applied
showColumns: comma separated list of column names to hide or keep (the filter is applied if one is set)
labelquery parameter. Only applied if the
labelquery parameter is set.
label: can be a single value or a path to a row in a subtable. To descend into subtables, the value should contain the
>character, for example,
urldir>urlsubdir>index. Can also be an array of values, for example,
There are some other special query parameters that affect the way reports are processed:
disable_generic_filters: If set to
1, the filters numbered 2 - 9 above will not be applied. Defaults to
0so if this parameter is absent, the filters will be applied.
format: Determines the output format of the return value. This affects all return values regardless of whether it is a report or a scalar value.
The output of a Reporting API request is a serialized string of the API method's return value. The format of this string is determined by the value of the format query parameter. Currently Piwik supports the following output formats:
There is a special output format value, original, that can be used when requesting data from within Piwik using
Piwik\API\Request. This format will force the result to be returned as unprocessed and unserialized data. It should only be used when calling the API within Piwik in PHP.
Request::processRequest() method automatically uses the original format, so in most cases you won't need to specify
Some of the API methods in the API plugin have special meaning and uses:
The API.getMetadata, API.getReportMetadata and API.getProcessedReport API methods can be used to get information about one or all reports. The information includes the metrics contained in the report, documentation for those metrics and more.
These methods can be used by third party applications that provide an interface to the analytics stored by Piwik:
API.getReportMetadatareturns metadata for every report, it can be used to get a list of all available reports for a website
API.getMetadatacan be used to get more information about a single report
API.getProcessedReportcan be used to get the metadata of a single report along with the report's data.
Report metadata can also be used within Piwik for features that operate on report(s) specified by the user. For example, the ImageGraph plugin, which outputs an image of a graph using report data, uses report metadata values as hints for how to draw the output graph. The ScheduledReports plugin also uses report metadata in a similar way.
Piwik's row evolution feature that is available through the UI is also available through the Reporting API. Third party applications can use the API.getRowEvolution method to get both single row evolution data or multi-row evolution data.
Like the Tracking API, the Reporting API supports bulk requests. A bulk request allows applications to invoke and retrieve the results for multiple API methods with one HTTP request. This can be used to save time in applications that query the Piwik HTTP API.
To send a bulk request, send an HTTP request to the API.getBulkRequest API method. The only required query parameter is named
urls. It should be an array of individual API request URLs. For example:
This example uses the following API requests:
Note: The separate API methods are executed synchronously, so for long running API methods, using a bulk request may be a bad idea.
getAPI method of all loaded plugins that support it and merges the result. The
getmethods all output the metrics that the plugin archives, so the result of API.get is the set of values for every metric your Piwik install supports (for the specified website & period).
type: The type of segment dimension.
category: A translated string that describes the segment dimension's category.
name: A translated string or a translation token that describes the segment dimension itself.
segment: The segment dimension's ID. This is what gets used in segment expressions.
acceptedValues: A string that describes what values should be used with the segment dimension.
sqlSegment: The table column the segment dimension operates on, for example,
sqlFilterValue: An optional PHP callback that transforms the value supplied in a segment expression before it is used in an SQL expression.
permission: Whether the current user can use this segment dimension.