Read this guide if
Guide assumptions
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, UserSettings.getBrowser.
API requests are processed in the following way:
API::index() controller method creates a Piwik\API\Request instance and uses it to dispatch the API request.Request instance uses the method query parameter to determine which plugin and API method to use.Request instance 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, idSite query parameter will be passed as the $idSite method parameter.Request instance uses a ResponseBuilder instance 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:
@ignore tagQuery 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:
DataTable or DataTable\Map instancesNote: When returning DataTable or DataTable\Map instances, filters will need to applied. Make sure to queue filters that are used for presentation purposes and directly apply other ones.
If a method throws an exception its message will appear in the output. The stack trace can be displayed during debugging by changing ResponseBuilder::DISPLAY_BACKTRACE_DEBUG to true.
You can see the list of all API methods your Matomo install exposes: click the API link in the top menu. See the demo's list here.
Reports returned by API methods (i.e. DataTable or DataTable\Map instances) are processed before being outputted.
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:
DataTable hierarchy into one DataTable, adding rows of subtables to their parent rows.
flat: set to 1 to apply the filterDataTable that 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 (label column by default)DataTable for 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 (label column by default)filter_excludelowpop: column to filter (the filter is applied if set)filter_excludelowpop_value: minimum threshold value (defaults to 0)filter_add_columns_when_show_all_columns: set to 1 to apply the filterfilter_update_columns_when_show_all_goals: set to 1 to apply the filteridGoal: ID of a goal or one of these special values:
AddColumnsProcessedMetricsGoal::GOALS_OVERVIEW (default): adds metrics for the goals overview and not individual goalsAddColumnsProcessedMetricsGoal::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 goalfilter_sort_column: column to sort (the filter is applied if set)filter_sort_order: 'desc' or 'asc'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 rangekeep_summary_row: if set to 1, the summary row is kept in the reportlabel column 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 appliedhideColumns or showColumns: comma separated list of column names to hide or keep (the filter is applied if one is set)label query parameter. Only applied if the label query 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, label[]=arg1&label[]=arg2.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 0 so 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 Matomo supports the following output formats:
There is a special output format value, original, that can be used when requesting data from within Matomo 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 Matomo in PHP.
Note: The Request::processRequest() method automatically uses the original format, so in most cases you won't need to specify format=original.
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 Matomo:
API.getReportMetadata returns metadata for every report, it can be used to get a list of all available reports for a websiteAPI.getMetadata can be used to get more information about a single reportAPI.getProcessedReport can be used to get the metadata of a single report along with the report's data.Report metadata can also be used within Matomo 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.
Matomo'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 Matomo 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:
https://demo.matomo.org/?module=API&method=API.getBulkRequest&format=xml&urls[]=module%3DAPI%26method%3DVisitorInterest.getNumberOfVisitsPerVisitDuration%26format%3DXML%26idSite%3D62%26period%3Dday%26date%3D2013-11-24%26expanded%3D1&urls[]=module%3DAPI%26method%3DUserSettings.getBrowser%26format%3DXML%26idSite%3D7%26period%3Dday%26date%3D2013-11-24%26expanded%3D1
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.
get API method of all loaded plugins that support it and merges the result. The get methods all output the metrics that the plugin archives, so the result of API.get is the set of values for every metric your Matomo 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, log_visit.idvisitor.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.