enuno/matomo-api

Matomo API Skill

Comprehensive API reference for Matomo (formerly Piwik), the open-source web analytics platform. Covers tracking APIs, reporting APIs, JavaScript/PHP clients, and database schema.

When to Use This Skill

This skill should be triggered when:

• Implementing Matomo tracking on websites or applications
• Building integrations with Matomo's Reporting API
• Querying analytics data programmatically
• Setting up event tracking, goal conversions, or ecommerce tracking
• Working with Matomo's JavaScript or PHP tracking clients
• Understanding Matomo's database structure for custom queries
• Implementing consent management and privacy controls
• Debugging Matomo tracking issues

Quick Reference

Tracking HTTP API Endpoint

https://your-matomo-domain.example/matomo.php

Required Parameters:

• idsite - Website ID being tracked
• rec=1 - Required to enable tracking

Common Parameters:

• action_name - Page title for pageviews
• url - Full URL of the current action
• _id - 16-character hexadecimal visitor ID
• rand - Random value to prevent caching
• apiv=1 - API version

Event Tracking Parameters

• e_c - Event category
• e_a - Event action
• e_n - Event name
• e_v - Event value (numeric)

Goal Conversion

• idgoal - Goal ID to trigger conversion
• revenue - Monetary value for conversion

Ecommerce Parameters

• ec_id - Order ID
• ec_items - JSON array of items
• revenue - Total order value
• ec_st - Subtotal
• ec_tx - Tax
• ec_sh - Shipping
• ec_dt - Discount

Reporting API Endpoint

https://your-matomo-domain.example/index.php?module=API&method=MODULE.METHOD&format=FORMAT

Standard Parameters: | Parameter | Values | Purpose | |-----------|--------|---------| | idSite | Integer or comma-separated | Website ID(s) | | period | day, week, month, year, range | Time period | | date | YYYY-MM-DD or magic keywords | Specific date | | format | xml, json, csv, tsv, html, rss | Output format | | token_auth | Your API token | Authentication |

Date Magic Keywords:

• today, yesterday
• lastWeek, lastMonth, lastYear
• lastX (e.g., last7)
• previousX (e.g., previous30)

JavaScript Tracking

// Page view
_paq.push(['trackPageView', 'Custom Page Title']);

// Event
_paq.push(['trackEvent', 'Category', 'Action', 'Name', Value]);

// Goal conversion
_paq.push(['trackGoal', goalId, customRevenue]);

// Site search
_paq.push(['trackSiteSearch', 'keyword', 'category', resultsCount]);

// Ecommerce order
_paq.push(['trackEcommerceOrder', orderId, grandTotal, subTotal, tax, shipping, discount]);

PHP Tracking

use MatomoTracker;

$tracker = new MatomoTracker($idSite, 'https://matomo.example.com/');
$tracker->setTokenAuth($token);
$tracker->setUserId($userId);
$tracker->doTrackPageView('Page Title');
$tracker->doTrackEvent('Category', 'Action', 'Name', $value);
$tracker->doTrackGoal($idGoal, $revenue);

Consent Management (JavaScript)

// Require consent before tracking
_paq.push(['requireConsent']);

// When user gives consent
_paq.push(['setConsentGiven']);

// Cookie-specific consent
_paq.push(['requireCookieConsent']);
_paq.push(['rememberCookieConsentGiven', hoursToExpire]);

// Opt-out
_paq.push(['optUserOut']);

Reference Files

This skill includes comprehensive documentation in references/:

• tracking-http-api.md - HTTP Tracking API specification
• reporting-api.md - Reporting API methods and parameters
• javascript-client.md - JavaScript Tracking Client reference
• php-client.md - PHP Tracking Client reference
• database-schema.md - Database tables and relationships

Common Patterns

Bulk Tracking (HTTP)

POST https://matomo.example.com/matomo.php
{
  "requests": [
    "?idsite=1&rec=1&url=https://example.org/page1",
    "?idsite=1&rec=1&url=https://example.org/page2"
  ],
  "token_auth": "your_token_here"
}

Bulk API Requests (Reporting)

?module=API&method=API.getBulkRequest
&urls[0]=method%3DVisitsSummary.get%26idSite%3D1%26period%3Dday%26date%3Dtoday
&urls[1]=method%3DActions.getPageUrls%26idSite%3D1%26period%3Dday%26date%3Dtoday

Segmentation

# Visits from mobile devices in United States
&segment=deviceType==smartphone;countryCode==us

# Visits with specific event
&segment=eventCategory==Video;eventAction==Play

PHP Bulk Tracking

$tracker->enableBulkTracking();
$tracker->doTrackPageView('Page 1');
$tracker->doTrackPageView('Page 2');
$tracker->doTrackEvent('Category', 'Action');
$tracker->doBulkTrack(); // Send all at once

Key API Modules

Visitor Analytics

• VisitsSummary - Overall visit metrics
• UserCountry - Geographic data
• DevicesDetection - Device and browser info
• UserLanguage - Language preferences

Actions & Content

• Actions - Pages, downloads, outlinks
• Events - Custom event tracking
• Contents - Content impression tracking

Conversions

• Goals - Goal conversions and revenue
• Ecommerce - Ecommerce transactions

Traffic Sources

• Referrers - Traffic source analysis
• MarketingCampaignsReporting - Campaign tracking

Real-time

• Live - Real-time visitor data
• Live.getLastVisitsDetails - Recent visitor details

Core Metrics

| Metric | Description | |--------|-------------| | nb_uniq_visitors | Unique visitors | | nb_visits | Total visits (30-min session) | | nb_actions | Page views, downloads, outlinks | | bounce_rate | Single-page visit percentage | | avg_time_on_page | Average page duration | | revenue | Goal/ecommerce revenue | | conversion_rate | Goal achievement ratio |

Database Tables

Log Data (Raw)

• log_visit - Individual visits
• log_link_visit_action - Actions within visits
• log_action - Action definitions (URLs, titles)
• log_conversion - Goal conversions
• log_conversion_item - Ecommerce items

Archive Data (Aggregated)

• archive_numeric_YYYY_MM - Numeric metrics
• archive_blob_YYYY_MM - Report data (compressed)

Configuration

• site - Website configuration
• goal - Goal definitions
• segment - Saved segments
• user - User accounts
• access - User permissions

Authentication

Token Authentication

&token_auth=YOUR_TOKEN_HERE

• Create tokens in: Administration > Personal > Security > Auth tokens
• Never share URLs containing tokens publicly
• Use POST requests with token in body for enhanced security

Features Requiring Auth

• IP address override (cip)
• Custom timestamp (cdt)
• Geolocation override (country, region, city, lat, long)

Performance Tips

1. Use Bulk Tracking - Batch multiple tracking calls
2. Cache API Responses - Set appropriate cache headers
3. Use Segments Sparingly - Complex segments impact performance
4. Archive Data - Query archive tables for historical reports
5. Limit Results - Use filter_limit to restrict row counts

Resources

• Official API Documentation
• Tracking HTTP API
• Reporting API
• JavaScript Client
• PHP Client
• Database Schema

Notes

• Matomo was formerly known as Piwik
• API supports both Matomo 4.x and 5.x versions
• Session timeout default is 30 minutes
• Visitor ID is 16-character hexadecimal
• All tracking requests should include rec=1 parameter