Skip to main content

Python wrapper for the Matomo reporting API

Project description

Python wrapper for the Matomo Reporting API

Release warning for users of versions 1.0b4 and before

This version is not backward compatible with earlier versions since it breaks on how to import and use it. Previous versions used the deprecated from matomo_api import * to literally enter all names that Matomo uses in their API into the receiving namespace. That cluttered the receiving namespace more than was preferable and introduced naming conflicts on identifiers such as format and date.
This version departs from this approach and uses the standard import matomo_api instead. This necessitates qualifying all API identifiers with the name of the module, or an alias as set by using import matomo_api as ma. See the usage example below for further details.


This Python wrapper is based on (scraped) information from Matomo's developer and glossary sites, together with the contents of the getReportMetadata and getGlossaryMetrics API Requests.

The design goal for this package has been to provide API documentation from within the Python environment. Classes, methods and their respective docstrings have been used to facilitate this, thus enabling IDE popup/autocomplete options to aid in setting up an API Query.
Names of the API Modules, Methods, and parameters in this package follow Matomo documentation. Since this also holds for any capitalization, this diverts from Python naming conventions.

Note on terminology

Python and the Matomo API clash on some terminology. Most prone to raise confusion are the terms module and method. To distinguish in which context these terms are used, they will be capitalized when referring to the Matomo API, while lowercase will be used for a Python context.

To add to the confusion, Matomo uses the term Module in two interpretations:

  • Group of related API Methods, e.g. 'Actions' or 'Events'. In API Queries it is the first part of the 'method' parameter, such as 'Actions' in method=Actions.getPageUrls.
  • Handler of all http API Requests (request parameter is module=API) as opposed to e.g. the handler of the web-gui (module=CoreHome).

In this documentation only the first interpretation is used: a Module is a collection of API Methods.

General usage instructions

  • Instantiate an object of the MatomoApi class, while specifying the server url and authorization token.

  • Select (and instantiate) an API Module by using the autocomplete/popup of your IDE on this MatomoApi object.

  • Select and use a specific API Method by again using the IDE autocomplete/popup features on the selected API Module.

  • The parameter/value combinations for the API Query can be selected by typing the parameter name, reading potential docstrings and sub-selecting attributes or methods via IDE popups/autocompletes. Apply these parameters by bundling them via the union operator | and use this bundle (actually a library) as argument for the selected API Method.

  • Wherever columns need to be specified, select them using the col class and sub-select via dot-notation using (again) the IDE popup/autocomplete.

Typical usage example:

import matomo_api as ma

URL = ''
TOKEN = '0b1c64cb1de641e36de6bc9dd658d47ab'

api = ma.MatomoApi(URL, TOKEN)

pars = ma.format.json | ma.language.da | ma.translateColumnNames() \
       | ma.idSite.one_or_more(1) | | \
       | ma.showColumns(, ma.col.label)

qry_result = api.Actions().getExitPageUrls(pars)

Elaboration of usage example

Instantiate the API

api = ma.MatomoApi(URL, TOKEN)

Variable api is assigned an instance of the MatomoApi class with actual server url and token as arguments.
Documentation of this class as popup:

MatomoApi class popup

Select and set parameters

pars = ma.format.json | ma.language.da | ma.translateColumnNames() \
       | ma.idSite.one_or_more(1) | | \
       | ma.showColumns(, ma.col.label)

Variable pars is assigned a union of API parameters that build the Query. All parameters are available as either Python class or Python function.

Autocompletion for an API parameter:

formatparameter autocomplete

In case the API parameter is represented by a Python class, values are set by selecting a class attribute or method. The documentation guides this selection:

format parameter popup

Autocomplete for setting the values of this format API parameter:

format parameter attributes

The idSite API parameter uses a class method to set multiple site id's:

idSite parameter popup

Some API parameters require column specifications, e.g. the showColumns parameter:

hideColumns parameter popup

To specify these columns, use the col class:

col class attributes autocomplete

Complete the Query

qry_result = api.Actions().getExitPageUrls(pars)

The methods of the MatomoApi class represent Matomo API Modules. Use method autocomplete on the api object to select the API Module:

MatomoApi methods autocomplete

Popup documentation of an API method:

Actions method popup

Upon using a MatomoApi class method, an object is instantiated representing an API Module with all its Methods. These API Methods can be selected via autocompletion of this 'Module' object:

Actions module autocomplete

Most Methods of an API Module have extensive documentation.

getExitPageUrls method popup

Using a Method returns the result of the API Query as Response object.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matomo_api-1.0b5.tar.gz (69.6 kB view hashes)

Uploaded source

Built Distribution

matomo_api-1.0b5-py3-none-any.whl (68.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page