Tracking API Reference

Please check the official Piwik API documentation as well:


class piwikapi.tracking.PiwikTracker(id_site, request)

The Piwik tracker class

  • id_site (int) – Site ID
  • request (A Django-like request object) – Request
Return type:



Length of the visitor ID

KNOWN_PLUGINS = {'director': 'dir', 'quick_time': 'qt', 'silverlight': 'ag', 'java': 'java', 'gears': 'gears', 'real_player': 'realp', 'pdf': 'pdf', 'flash': 'fla', 'windows_media': 'wma'}

List of plugins Piwik knows


Set the time

Parameters:datetime (datetime.datetime object) – Time
Return type:None

Set the auth token for the request. The token can be viewed in the user management section of your Piwik install.

Parameters:token_auth (str) – Auth token
Return type:None

Set which Piwik API URL to use

Parameters:api_url (str) – API URL
Return type:None

Set the IP to be tracked. You probably want to use this as the request comes from your own server.

Requires setting the auth token.

Parameters:ip (str) – IP
Return type:None

Call this is the browser supports cookies

Return type:None

Set the browser language. Piwik uses this to guess the visitor’s origin when GeoIP is not enabled

Parameters:language (str) – Accept-Language
Return type:None

Set the user agent. By default the original request’s UA is used.

Parameters:user_agent (str) – User agent
Return type:None
set_resolution(width, height)

Set the visitor’s screen width and height

  • width (int or str) – Screen width
  • height (int or str) – Screen height
Return type:


Parameters:visitor_id (str) – Visitor I
Raises:InvalidParameter if the visitor_id has an incorrect length
Return type:None
Parameters:string (str) – str to append
Return type:None

Set the referer URL

Parameters:referer (str) – Referer
Return type:None

Set URL being tracked

Parameters:url (str) – URL


Set the attribution info for the visit, so that subsequent goal conversions are properly attributed to the right referer, timestamp, campaign name and keyword.

This must be a JSON encoded string that you would normally fetch from the Javascript API, see function getAttributionInfo() in

Parameters:json_encoded (string) – JSON encoded list containing attribution info
Raises:InvalidParameter if the json_encoded data is incorrect
Return type:none

Override the server date and time for the tracking request.

By default Piwik tracks requests for the “current” datetime, but this method allows you to track visits in the past. Time are in UTC.

Requires setting the auth token.

Parameters:datetime (datetime.datetime object) – datetime
Return type:None

PARTIAL, no cookie support

If the user initiating the request has the Piwik first party cookie, this function will try and return the ID parsed from this first party cookie.

If you call this function from a server, where the call is triggered by a cron or script not initiated by the actual visitor being tracked, then it will return the random Visitor ID that was assigned to this visit object.

This can be used if you wish to record more visits, actions or goals for this visitor ID later on.

Return type:str


To support this we’d need to parse the cookies in the request obejct. Not sure if this makes sense...

Return the currently assigned attribution info stored in a first party cookie.

This method only works if the user is initiating the current request and his cookies can be read by this API.

Return type:string, JSON encoded string containing the referer info for goal conversion attribution

Return a random visitor ID

Return type:str


By default, PiwikTracker will read third party cookies from the response and sets them in the next request.

Return type:None

Track a page view, return the request body

Parameters:document_title (str) – The title of the page the user is on
Return type:str
do_track_action(action_url, action_type)

Track a download or outlink

  • action_url (str) – URL of the download or outlink
  • action_type (str) – Type of the action, either ‘download’ or ‘link’

InvalidParameter if action type is unknown

Return type:


set_custom_variable(id, name, value, scope='visit')

Set a custom variable


  • id (int) – Custom variable slot ID, 1-5
  • name (str) – Variable name
  • value (str) – Variable value
  • scope (str or None) – Variable scope, either visit or page, defaults to visit
Return type:



Set supported plugins

>>> piwiktrackerinstance.set_plugins(flash=True)

See KNOWN_PLUGINS keys for valid values.

Parameters:kwargs (dict of {str: int}) – A plugin: version dict, e.g. {‘java’: 6}, see also KNOWN_PLUGINS
Return type:None
get_custom_variable(id, scope='visit')

PARTIAL, no cookie support

Returns the current custom variable stored in a first party cookie.

  • id (int) – Custom variable slot ID, 1-5
  • scope (str) – Variable scope, either visit or page
Return type:

mixed stuff TODO


class piwikapi.tracking.PiwikTrackerEcommerce(id_site, request)

The Piwik tracker class for ecommerce

add_ecommerce_item(sku, name=False, category=False, price=False, quantity=1)

Add an item to the ecommerce order.

This should be called before do_track_ecommerce_order() or before do_track_ecommerce_cart_update().

This method can be called for all individual products in the cart/order.

  • sku – Product SKU
  • name (str or None) – Name of the product
  • category (str, list or None) – Name of the category for the current category page or the product
  • price (int or None) – Price of the product
  • quantity – Product quantity, defaults to 1
Return type:



Track a cart update (add/remove/update item)

On every cart update you must call add_ecommerce_item() for each item in the cart, including items which were in the previous cart. Items get deleted until they are re-submitted.

Parameters:grand_total (float) – Grand total revenue of the transaction, including taxes, shipping, etc.
Return type:str
do_track_ecommerce_order(order_id, grand_total, sub_total=False, tax=False, shipping=False, discount=False)

Track an ecommerce order

If the order contains items you must call add_ecommerce_item() first for each item.

All revenues will be individually summed and reported by Piwik.

  • order_id (str) – Unique order ID (required). Used to avoid re-recording an order on page reload.
  • grand_total (float) – Grand total revenue of the transaction, including taxes, shipping, etc.
  • sub_total (float or None) – Sub total amount, typicalle the sum of item prices for all items in this order, before tax and shipping
  • tax (float or None) – Tax amount for this order
  • shipping (float or None) – Shipping amount for this order
  • discount (float or None) – Discount for this order
Return type:


do_track_goal(id_goal, revenue=False)

Record a goal conversion

  • id_goal (int) – Goal ID
  • revenue (int (TODO why int here and not float!?)) – Revenue for this conversion
Return type:


set_ecommerce_view(sku=False, name=False, category=False, price=False)

Set the page view as an item/product page view, or an ecommerce category page view.

This method will set three custom variables of ‘page’ scope with the SKU, name and category for this page view.

On a category page you may set the category argument only.

Tracking product/category page views will allow Piwik to report on product and category conversion rates.

To enable ecommerce tracking see doc/install.rst

  • SKU (str or None) – Product SKU being viewed
  • name (str or None) – Name of the product
  • category (str, list or None) – Name of the category for the current category page or the product
  • price (float or None) – Price of the product
Return type: