Matomo Search Engine & Social List

Matomo Search Engine and Social List is a community-maintained set of definitions that map URLs to the search engines, social networks, and AI assistants that produced them. Maintained by the Matomo analytics project, it powers referrer detection so analytics tools can classify where visitors came from.

The definitions are stored as human-readable YAML files, one per category, listing each provider’s name alongside the hostnames and search-keyword parameters used to recognise it. Packaged for Composer, it lets any project reuse Matomo’s referrer-classification data.

What You Get

• SearchEngines.yml defining search engines, their hosts, and keyword parameters
• Socials.yml defining social networks and their associated URLs
• AIAssistants.yml defining AI assistant sources for referrer detection
• A human-readable YAML format that is easy to extend via pull request
• Composer packaging for reuse in any PHP analytics project

Common Use Cases

• Classifying referrer URLs as search engines, social networks, or AI assistants
• Extracting search keywords from referrer query strings
• Building traffic-source attribution in an analytics product
• Keeping referrer-detection data in sync with a community source

Under The Hood

Architecture - The repository is a data set, not a codebase: SearchEngines.yml, Socials.yml, and AIAssistants.yml enumerate providers as keyed lists of URLs and parameters. Consumers parse the YAML into lookup structures and match a referrer’s host (and, for search, its query parameters) to resolve the source and any embedded keyword. The curation and review process is the substance of the project.

Tech Stack - Plain YAML data files distributed via Composer/Packagist (a package.json is also present for JavaScript consumers). There is no runtime logic; any YAML parser in any language can load the definitions.

Code Quality - Quality is about data accuracy and coverage: entries are contributed and reviewed through pull requests, the format is consistent across files, and the list is broad and periodically updated. It underpins referrer detection in Matomo itself.

API Design - The interface is the YAML schema: a provider name mapping to one or more URLs, with optional keyword parameters for search engines. That predictable shape makes it straightforward to load and match against referrers.