commit	d07b8eb0671bbbc0dd5f43efc7193136e569908d	[log] [tgz]
author	Marc Kupietz <kupietz@ids-mannheim.de>	Sat Apr 22 23:23:18 2023 +0200
committer	Marc Kupietz <kupietz@ids-mannheim.de>	Sat Apr 22 23:23:18 2023 +0200
tree	9fc88253f21bd5649109531f5222a235971e542d
parent	e4b79544a7bfc032deb113a620d84eb1bc95d470 [diff]

tree: 9fc88253f21bd5649109531f5222a235971e542d

Readme.md

R client library to access the Matomo web service API

Description

The package provides client access to the web service API of the web analytics platform Matomo.

Installation Prerequisites

Windows

You need to install git to be able to access the development version of matomor.

Linux

matomor uses some R packages with system dependencies you might need to install first:

#### Debian / Ubuntu
sudo apt install r-base-dev libcurl4-gnutls-dev libxml2-dev libsodium-dev libgit2-dev

#### Fedora / CentOS >= 8 / RHEL >= 8
sudo dnf install R-devel libcurl-devel openssl-devel libxml2-devel libsodium-devel libgit2-devel

#### CentOS < 8 / RHEL < 8
sudo yum install R-devel libcurl-devel openssl-devel libxml2-devel libsodium-devel libgit2-devel

#### Arch Linux
pacman -S base-devel gcc-fortran libsodium curl libgit2

Installation

library(devtools)
install_git("https://korap.ids-mannheim.de/gerrit/IDS-Mannheim/matomor")

Documentation

See matomo Reporting API Reference for details.

NOTE: Currently, the date column in the data frame results refers to the first day of the respective period.

Usage

getVisitsSummary(
  matomoUrl,
  siteId,
  period = "month",
  date = "last16",
  filter_limit = 100,
  removeFirst = FALSE,
  removeLast = FALSE,
  accessToken = getAccessToken(matomoUrl)
)

Arguments

Argument	Description
`matomoUrl`	base URL of your matomo instance
`siteId`	matomo site id or vector of site ids
`period`	day, week, month or year
`date`	date range (see matomo API reference)
`filter_limit`	defines the maximum number of rows to be returned
`removeFirst`	logical that determines whether the first row of each site should be removed (to account for incomplete periods)
`removeLast`	logical that determines whether the last row of each site should be removed (to account for incomplete periods)
`accessToken`	API Authentication Token - you can get this in your matomo interface under Settings -> Personal -> Settings -> API Authentication Token and pass it here, or you can make it persistent with persistAccessToken.

Result

Data frame with the following columns: (see Matomo API Response: Metric Definitions for a more detailed and authoritative description)

Column	Description
`c("day","month","year")`	date (range)
`nb_uniq_visitors`	Number of unique visitors
`nb_users`	Number of unique active users (visitors with a known User ID). If you are not using User ID then this metric will be set to zero.
`nb_visits`	Number of Visits (30 min of inactivity considered a new visit)
`nb_actions`	Number of actions (page views, outlinks and downloads)
`nb_visits_converted`	Number of visits that converted a goal
`bounce_count`	Number of visits that bounced (viewed only one page)
`sum_visit_length`	Total time spent, in seconds
`max_actions`	Maximum number of actions in a visit
`avg_time_on_site`	Average time spent, in seconds, on this site
`site_id`	Id of requested site (provided by matomor)
`date`	interpolated date (provided matomor)

Example result data frame returned from a query with period `month`.

month	nb_uniq_visitors	nb_visits	nb_actions	bounce_count	sum_visit_length	max_actions	bounce_rate	nb_actions_per_visit	avg_time_on_site	site_id	date
2020-06	343	3737	70554	851	3595243	724	23%	18.9	962	3	2020-06-01
2020-07	1048	2695	55163	650	2599097	2064	24%	20.5	964	3	2020-07-01
2020-08	823	2707	60570	581	2978008	631	21%	22.4	1100	3	2020-08-01
2020-09	949	3222	74976	691	3564482	836	21%	23.3	1106	3	2020-09-01
2020-10	1254	3624	69954	901	3548351	1089	25%	19.3	979	3	2020-10-01
2020-11	1805	5005	108621	1108	5325212	1308	22%	21.7	1064	3	2020-11-01
2020-12	1134	2713	62353	574	3015877	565	21%	23	1112	3	2020-12-01

Examples

Plot with ggplot

library(matomor)
library(tidyverse)
library(idsThemeR)

# persistAccessToken("https://stats.xxx.org/", "ad7609a669179c4ebca7c995342f7e09")

getVisitsSummary("https://stats.xxx.org/", siteId = c(8,14), period="day", date="last60") %>%
     mutate(service = case_when(site_id == 8 ~ "A", site_id == 14 ~ "B")) %>%
     ggplot(aes(date, nb_visits, color=service)) + 
     scale_color_ids() + theme_ids() +
     geom_smooth(span=.3, se=FALSE)

Plot with highcharter

library(matomor)
library(tidyverse)
library(highcharter)
library(idsThemeR)

# persistAccessToken("https://stats.xxx.org/", "ad7609a669179c4ebca7c995342f7e09")

getVisitsSummary("https://stats.xxx.org/", siteId = c(13,14), period="month", date="last16") %>%
  mutate(service = case_when(site_id == 13 ~ "A", site_id == 14 ~ "B")) %>%
  hchart("spline", hcaes(date, nb_actions, group=service)) %>%
  hc_add_theme(hc_theme_ids_light())

Integration of non-matomo data in CSV format

library(matomor)
library(tidyverse)
library(highcharter)
library(idsThemeR)

serviceC_usage <- read.csv('./inst/exdata/serviceC_usage.csv') %>%
  mutate(service="C", date=as.Date(date)) %>%
   filter(date >= as.Date("2019-09-01"))

# matomoUtl <- "https://stats.xxx.org/"

getVisitsSummary(matomoUrl, siteId = c(13,14), period="month", date="2019-09-01,2020-11-01", removeLast=T) %>%
  mutate(service = case_when(site_id == 13 ~ "A", site_id == 14 ~ "B")) %>%
  bind_rows(serviceC_usage) %>%
  hchart("spline", hcaes(date, nb_visits, group=service)) %>%
  hc_add_theme(hc_theme_ids_light())

Actions per month from Jan 2019 until the end of last month saved as PNG

library(matomor)
library(idsThemeR)
library(lubridate)
library(tidyverse)
end_of_last_month <- floor_date(Sys.Date(), "month") - 1

getVisitsSummary("https://stats.xxx.de/", siteId = c(13,14), period="month",
  date=paste0("2019-01-01,", end_of_last_month)) %>%
      mutate(Service = case_when(site_id == 13 ~ "Angebot A", site_id == 14 ~ "Angebot B")) %>%
      ggplot(aes(date, nb_actions, col = Service, group = Service)) +
      scale_x_date(date_labels = "%b %y") +
      theme_ids() +
      scale_color_ids() +
      xlab("") +
      ylab("Abfragen") +
      labs(color = NULL) +
      scale_y_continuous(labels = scales::label_number_si()) +
      geom_point() +
      geom_line()

ggsave("./man/figures/AB-actions.png", width = 70 * .pt, height = 30 * .pt,  units = "mm", dpi = 600)

Development and License

Authors: Marc Kupietz

This package is developed as part of the KorAP Corpus Analysis Platform at the Leibniz Institute for German Language (IDS).

It is published under the BSD-2 License.

Contributions

Contributions are very welcome!

Your contributions should ideally be committed via our Gerrit server to facilitate reviewing (see Gerrit Code Review - A Quick Introduction if you are not familiar with Gerrit). However, we are also happy to accept comments and pull requests via GitHub.

Please note that unless you explicitly state otherwise any contribution intentionally submitted for inclusion into this software shall – as this software itself – be under the BSD-2 License.