Matomo API

Apps

class integreat_cms.matomo_api.apps.MatomoApiConfig(app_name, app_module)

Bases: AppConfig

MatomoApiClient config inheriting the django AppConfig

name: Final[str] = 'integreat_cms.matomo_api'

Full Python path to the application

verbose_name: Final[Promise] = 'Matomo API'

Human-readable name for the application

Matomo API Client

class integreat_cms.matomo_api.matomo_api_client.MatomoApiClient(region: Region)

Bases: object

This class helps to interact with Matomo API. There are three functions which can be used publicly:

• get_matomo_id(): Retrieve the Matomo ID belonging to the given Matomo access token

• get_total_visits(): Retrieve the total visits for the current region

• get_visits_per_language(): Retrieve the visits for the current region by language

Parameters:

region (Region)

__init__(region: Region) → None

Constructor initializes the class variables

Parameters:

region (Region) – The region this Matomo API Manager connects to

Return type:

None

async fetch(session: ClientSession, **kwargs: Any) → dict[str, Any] | list[int]

Uses aiohttp.ClientSession.get() to perform an asynchronous GET request to the Matomo API.

Parameters:

• session (ClientSession) – The session object which is used for the request

• **kwargs (Any) – The parameters which are passed to the Matomo API

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Returns:

The parsed json result

Return type:

dict[str, Any] | list[int]

static get_access_data(total_visits: dict, webapp_downloads: dict, offline_downloads: dict) → tuple[list[dict], list[str]]

Structure the datasets for accesses in a chart.js-compatible format, returning it and the custom legend entries

Parameters:

• total_visits (dict) – The total amount of visits

• webapp_downloads (dict) – The amount of visits via the WebApp

• offline_downloads (dict) – The amount of offline downloads

Returns:

The chart.js-datasets and custom legend entries

Return type:

tuple[list[dict], list[str]]

static get_language_data(languages: list[Language], datasets: list[dict]) → tuple[list[dict], list[str]]

Structure the datasets for languages in a chart.js-compatible format, returning it and the custom legend entries

Parameters:

• languages (list[Language]) – The list of languages

• datasets (list[dict]) – The Matomo datasets

Returns:

The chart.js-datasets and custom legend entries

Return type:

tuple[list[dict], list[str]]

get_matomo_id(token_auth: str) → int

Returns the matomo website id based on the provided authentication key.

Parameters:

token_auth (str) – The Matomo authentication token which should be used

Raises:

MatomoException – When a ClientError was raised during a Matomo API request or the access token is not correct

Returns:

ID of the connected Matomo instance

Return type:

int

async get_matomo_id_async(**query_params: Any) → list[int]

Async wrapper to fetch the Matomo ID with aiohttp. Opens a ClientSession and calls fetch(). Called from get_matomo_id().

Parameters:

**query_params (Any) – The parameters which are passed to the Matomo API

Returns:

The parsed json result

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Return type:

list[int]

get_total_visits(start_date: date, end_date: date, period: str = 'day') → dict[str, Any]

Returns the total calls within a time range for all languages.

Parameters:

• start_date (date) – Start date

• end_date (date) – End date

• period (str) – The period (one of CHOICES - defaults to DAY)

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Returns:

The total visits in the ChartData format expected by ChartJs

Return type:

dict[str, Any]

async get_total_visits_async(query_params: dict[str, str | int | None]) → dict[str, Any]

Async wrapper to fetch the total visits with aiohttp. Opens a ClientSession and calls fetch(). Called from get_total_visits().

Parameters:

query_params (dict[str, str | int | None]) – The parameters which are passed to the Matomo API

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Returns:

The parsed json result

Return type:

dict[str, Any]

get_visits_per_language(start_date: date, end_date: date, period: str) → dict[str, Any]

Returns the total unique visitors in a timerange as defined in period

Parameters:

• start_date (date) – Start date

• end_date (date) – End date

• period (str) – The period (one of CHOICES)

Returns:

The visits per language in the ChartData format expected by ChartJs

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Return type:

dict[str, Any]

async get_visits_per_language_async(loop: AbstractEventLoop, query_params: dict[str, Any], languages: list[Language]) → list[dict[str, Any]]

Async wrapper to fetch the total visits with aiohttp. Opens a ClientSession, creates a Task for each language to call fetch() and waits for all tasks to finish with gather(). The returned list of gathered results has the correct order in which the tasks were created (at first the ordered list of languages and the last element is the task for the total visits). Called from get_visits_per_language().

Parameters:

• loop (AbstractEventLoop) – The asyncio event loop

• query_params (dict[str, Any]) – The parameters which are passed to the Matomo API

• languages (list[Language]) – The list of languages which should be retrieved

Raises:

MatomoException – When a ClientError was raised during a Matomo API request

Returns:

The list of gathered results

Return type:

list[dict[str, Any]]

languages: list[Language] = []

The active languages

matomo_id: int | None = None

Matomo ID

matomo_token: str | None = None

Matomo API-key

static simplify_date_labels(date_labels: KeysView[str], period: str) → list[Promise]

Convert the dates returned by Matomo to more readable labels

Parameters:

• date_labels (KeysView[str]) – The date labels returned by Matomo

• period (str) – The period of the labels (determines the format)

Returns:

The readable labels

Return type:

list[Promise]

exception integreat_cms.matomo_api.matomo_api_client.MatomoException

Bases: Exception

Custom Exception class for errors during interaction with Matomo