referer-parser Python library

This is the Python implementation of referer-parser, the library for extracting search marketing data from referer (sic) URLs.

The implementation uses the shared 'database' of known referers found in referers.yml.

The Python version of referer-parser is maintained by Don Spaulding.

Installation

$ pip install referer_parser

Usage

Create a new instance of a Referer object by passing in the url you want to parse:

from referer_parser import Referer

referer_url = 'http://www.google.com/search?q=gateway+oracle+cards+denise+linn&hl=en&client=safari'

r = Referer(referer_url)

The r variable now holds a Referer instance. The important attributes are:

print(r.known)              # True
print(r.referer)            # 'Google'
print(r.medium)             # 'search'
print(r.search_parameter)   # 'q'
print(r.search_term)        # 'gateway oracle cards denise linn'
print(r.uri)                # ParseResult(scheme='http', netloc='www.google.com', path='/search', params='', query='q=gateway+oracle+cards+denise+linn&hl=en&client=safari', fragment='')

Optionally, pass in the current URL as well, to handle internal referers

from referer_parser import Referer

referer_url = 'http://www.snowplowanalytics.com/about/team'
curr_url = 'http://www.snowplowanalytics.com/account/profile'

r = Referer(referer_url, curr_url)

The attributes would be

print(r.known)              # True
print(r.referer)            # None
print(r.medium)             # 'internal'
print(r.search_parameter)   # None
print(r.search_term)        # None
print(r.uri)                # ParseResult(scheme='http', netloc='www.snowplowanalytics.com', path='/about/team', params='', query='', fragment='')

The uri attribute is an instance of ParseResult from the standard library's urlparse module.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Distribution

The distribution process for Python looks like this:

$ ./sync_data.py
$ # Make changes to codebase.
$ # Bump version number in setup.py
$ pushd python
$ python setup.py sdist bdist_wheel --universal
$ twine upload dist/referer-parser-X.Y.Z.tar.gz
$ popd

Copyright and license

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.