6 min read

Matomo Importer

Available on Pro and above. The Matomo importer is a one-shot tool to bring your last 90 days of Matomo daily aggregates into Zenovay, so you do not lose context when you switch.

What this does

Reads 90 days of daily aggregates from Matomo: visits, pageviews, top sources, top pages, top countries, devices, operating systems, and browsers.
Writes them into Zenovay's analytics_daily table with imported_from='matomo' so they are clearly distinguishable from native Zenovay data.
Idempotent: re-importing the same period UPSERTs by date and overwrites cleanly without duplicates.
Normalizes Matomo's taxonomy to Zenovay's canonical names automatically — for example Matomo's Smartphone device class maps to Zenovay's Mobile, and version-suffixed operating systems (Windows 11, Android 14) are collapsed to their canonical family.

What this does NOT do

It does not import individual visitor sessions or the Visits Log.
It does not import custom events, goals, ecommerce/revenue, or real-time data.
It does not continuously sync — V1 is one-shot. Recurring sync is on the roadmap.

Prerequisites

A Zenovay account on Pro tier or higher.
Either a Matomo report export file, or a Matomo instance you can reach over HTTPS with an API auth token.

Method A — Upload a report export

Use this if your Matomo is on a locked-down network or you simply prefer not to share an API token.

1. Export from Matomo

In Matomo, open the report you want (for example Visitors → Overview or Behaviour → Pages), set the date range to the last 90 days, and use the Export widget to download a CSV or JSON file.

2. Open the Import tab

Navigate to your domain's detail page → Import tab. You'll see source tiles for Plausible (existing) and Matomo (new).

3. Upload the file

Click the Matomo tile → Upload export and select your CSV or JSON file. Zenovay parses the file, maps Matomo's columns to its own schema, normalizes device/OS/browser names, and shows a preview before writing anything.

4. Confirm

Review the preview (rows detected, date range, normalized dimensions) and click Import. The data lands in your dashboard with the Matomo origin marker.

Method B — Connect via the Matomo Reporting API

Use this for a hands-off import that pulls all supported dimensions in one pass.

1. Create an auth token in Matomo

In Matomo, go to Personal → Security → Auth tokens and create a new token. Copy the token_auth value — Matomo only shows it once.

2. Find your numeric site ID

In Matomo, the site ID (idSite) is the number shown in the URL when you view a site's reports, or under Administration → Websites → Manage. It is a plain integer such as 1 or 42.

3. Connect in Zenovay

Open the Matomo tile → Connect via API and enter:

Matomo base URL — the root of your Matomo install, e.g. https://analytics.example.com (no trailing path).
token_auth — the token from step 1.
Site ID — the numeric idSite from step 2.

4. Trigger the import

Click Import last 90 days. The import runs in the background; the UI polls every two seconds and shows a progress bar. A 90-day import typically completes in 30–60 seconds.

5. Review

When complete, you'll see a summary: rows imported, date range, and which dimensions were found. Imported data immediately appears in your dashboard with the Matomo origin marker.

A note on normalization

Matomo and Zenovay categorize technology slightly differently. Zenovay maps automatically so your imported and native data line up:

Matomo device class Smartphone → Zenovay Mobile; Tablet stays Tablet; Desktop stays Desktop.
Version-suffixed operating systems (Windows 11, macOS 15, Android 14, iOS 18) collapse to their canonical family (Windows, macOS, Android, iOS).
Browser names are matched to Zenovay's canonical list; minor/build versions are dropped.

If a value cannot be confidently mapped it is preserved verbatim rather than discarded.

Troubleshooting

"Could not reach Matomo"

Check the base URL has no trailing path and is reachable over HTTPS from the public internet. Matomo instances behind a VPN or IP allowlist cannot be reached by the importer — use Method A (file upload) instead.

"Invalid token_auth"

Regenerate the token under Personal → Security → Auth tokens and paste it again. A token scoped to a different Matomo user with no view access to the site will also fail here.

"Site not found"

The site ID must be the numeric idSite, not the site's name or domain. Confirm it under Administration → Websites → Manage.

"Unrecognized export format"

Method A accepts Matomo's native CSV and JSON exports. Re-exported, manually edited, or spreadsheet-resaved files may lose the header row Zenovay needs — re-download straight from Matomo's Export widget.

"Partial import"

This indicates Matomo returned fewer than 90 days of data — usually because the site is newer than 90 days, or some days had no traffic. Spot-check the imported range in your dashboard.

Data slightly differs from the Matomo dashboard

Matomo deduplicates and counts visits differently from Zenovay's native ingestion, and bot filtering differs. Expect small deltas. The imported_from='matomo' marker lets you filter to compare like-for-like.

Distinguishing imported data

Every imported row carries imported_from='matomo' on analytics_daily. In Zenovay's Public Stats API (Pro+), you can filter via the same field. Native Zenovay data has imported_from=NULL.

Re-importing and removal

Re-running the import for the same period UPSERTs by date, so it is safe to repeat. To remove imported Matomo data, open the Matomo tile and use Delete imported data — native Zenovay rows are untouched.

Need help? Contact [email protected] or visit our Help Center.