README

NOTE: Fork of Snowplow Referer Parser

referer-parser

referer-parser is a database for extracting marketing attribution data (such as search terms) from referer URLs, inspired by the ua-parser project (an equivalent library for user agent parsing).

The referer-parser project also contains multiple libraries for working with the referer-parser database in different languages.

referer-parser is a core component of Snowplow, the open-source web-scale analytics platform powered by Hadoop and Redshift.

Note that we always use the original HTTP misspelling of 'referer' (and thus 'referal') in this project - never 'referrer'.

Database

The latest database is always available on this URL:

https://s3-eu-west-1.amazonaws.com/snowplow-hosted-assets/third-party/referer-parser/referers-latest.yml

The database is updated at most once a month. Each new version of the database is also uploaded with a timestamp:

https://s3-eu-west-1.amazonaws.com/snowplow-hosted-assets/third-party/referer-parser/referers-YYYY-MM.yml

If there is an issue with the database necessitating a re-release within the month, the corresponding files will be overwritten.

Maintainers

• PHP: Lars Strojny
• referers.yml: Snowplow Analytics

Usage

The PHP version of this library uses the updated API, and identifies search, social, webmail, internal and unknown referers:

use Snowplow\RefererParser\Parser;

$parser = new Parser();
$referer = $parser->parse(
    'http://www.google.com/search?q=gateway+oracle+cards+denise+linn&hl=en&client=safari',
    'http://www.psychicbazaar.com/shop'
);

if ($referer->isKnown()) {
    echo $referer->getMedium(); // "Search"
    echo $referer->getSource(); // "Google"
    echo $referer->getSearchTerm();   // "gateway oracle cards denise linn"
}

For more information, please see the PHP README.

Contributing

We welcome contributions to referer-parser:

1. New search engines and other referers - if you notice a search engine, social network or other site missing from referers.yml, please fork the repo, add the missing entry and submit a pull request
2. Ports of referer-parser to other languages - we welcome ports of referer-parser to new programming languages (e.g. Lua, Go, Haskell, C)
3. Bug fixes, feature requests etc - much appreciated!

Please sign the Snowplow CLA before making pull requests.

Support

General support for referer-parser is handled by the team at Snowplow Analytics Ltd.

You can contact the Snowplow Analytics team through any of the channels listed on their wiki.

Copyright and license

referers.yml is based on Piwik's SearchEngines.php and Socials.php, copyright 2012 Matthieu Aubry and available under the GNU General Public License v3.

The PHP port is copyright 2013-2014 Lars Strojny and is available under the MIT License.