Go Back

Optional API parameters

June 12, 2018

Optional parameters in Piwik PRO API serve as filters either for data presentation (presentation filters) or data preprocessing (data helpers).

Presentation filters allow you to customize the display of your data.

With additional parameters you can perform initial data preprocessing like sorting, extracting a subset of data, fetch children of a given entity, etc.

Here you can find all optional parameters you may use while using the Piwik PRO API.

Translating output

language

This parameter, if specified, allows the API to return data strings that can be translated to other languages. This is especially useful when you have a report that will be presented to a multilingual audience.

With the language parameter, you can translate not only strings, but also, for example, dates.
Use two-character language codes for this parameter: en, de, pl, fr, es, etc.

Handling hierarchical data

expanded

Some data in Piwik PRO are hierarchical, as there are subtables attached to certain rows in main tables. While calling Piwik PRO API you can specify whether the output should include only first-level data or data including subtables. This parameter can take values of 0 (false) or 1 (true). If ‘expanded=1’ then the API call will return results with subtables.

idSubtable

A subtable is a table linked to row in a higher-level table. For example: each row in the Referrers.getSearchEngines response has an “idsubdatatable” field. This integer idsubdatatable is the idSubtable of the table that contains all the keywords for this search engine. You can then request the keywords for this search engine by calling Referrers.
Example: getKeywordsFromSearchEngineId with the parameter idSubtable=X (replace X with the idsubdatatable value found in the Referrers.getSearchEngines response, for the search engine you are interested in).

flat

This parameter, also used for hierarchical data, allows you to retrieve hierarchical data as a flat output. If ‘flat=1’, the returned data will contain the flattened view of the table data set. The children of all first level rows will be aggregated as separate rows.
Example: this is useful to see all Custom Variable names and values at once like for Piwik forum user status, or to see the full URLs not broken down by directory or structure.

Pivoting data

pivotBy

This parameter can be used to create a pivot table of a report using a specified dimension.

Pivoting a report will intersect a report with another one and display a single metric for values along two dimensions.
To pivot a report, this query parameter must be set to the ID of the dimension to pivot by. For example, pivotBy=Referrers.Keyword would pivot against the Keyword dimension.

Note: If you want to pivot against a dimension that is not the dimension of a report’s subtable, you must set the pivot_by_filter_enable_fetch_by_segment INI config variable to 1. Using segments will allow you to pivot by any dimension, but currently it is a slow operation.

pivotByColumn

This parameter specifies which column should be displayed in a pivoted report. It should be used with pivotBy and set to a column name, for example, nb_visits.

pivotByColumnLimit

This parameter can be used to specify the maximum number of columns that should be displayed in a pivot table. All other columns are aggregated into an ‘Others’ column.

Filtering data

filter_offset

This parameter can be used to define the offset of the starting row being returned by the API call.

filter_limit

This parameter defines the number of rows to be returned by the API call. By default it only returns the first 100 rows, while setting it to -1 will return all rows.

filter_truncate

Setting this parameter will truncate the table after $filter_truncate rows. The last row will be named ‘Others’ (localized in the requested language) and the columns will be an aggregate of statistics of all truncated rows

label

This parameter will help you to search for the row matching a specific label, filter it, and retrieve only that row.
Example: &label=best%20hotdogs

This will return only the row with the label “best hotdogs”

In the Piwik PRO API there are also generic filters you can choose to apply on all APIs that return web analytics reports. For example, there is a filter for sorting by column – you define the start and number of rows to return. There is also a filter to only return rows matching a given string.

filter_pattern

This parameter defines the text you want to search for in the filter_column. Only the row with the given column matching the pattern will be returned. The pattern will be interpreted as a regular expression.
Example: (en|pl|de)\.mydomain.

filter_column

This parameter defines the column where you want to search for the text in filter_pattern. If not specified, defaults to ‘label’ (label).

filter_sort_order

This parameter defines the order of the results. Can take values ‘asc’ or ‘desc’.

filter_sort_column

This parameter defines the column for data to be sorted by.

filter_excludelowpop

This parameter defines the column to use for the threshold of the value filter_excludelowpop_value. Only the columns with a value greater than filter_excludelowpop_value will be returned.

filter_excludelowpop_value

This parameter defines the minimum value for the filter_excludelowpop column.

filter_column_recursive

This parameter defines the column to be searched for when recursively searching for the pattern filter_pattern_recursive.

filter_pattern_recursive

This parameter defines the text you are searching for and is applied to recursive tables (Actions/Downloads/Outlinks tables).

disable_generic_filters

This parameter turns off all the generic filters above, if set to 1. This can be useful to disable the filters above which are otherwise applied with default values.

disable_queued_filters

This parameter, if set to 1, turns off all the filters that are mostly presentation filters (replace a column name, apply callbacks on the column to add new information such as the browser icon URL, etc.). Mostly used internally or when developing plugins for Piwik PRO.

hideColumns

This parameter takes a comma-separated list of columns. If set, it removes the specified columns from the result.

showColumns

This parameter takes a comma separated list of columns. If set, it removes all columns not specified in this list from the result.

Both parameters above can be used to reduce the amount of data transferred.