Tracking API: Reference

This page contains the API Reference for the Piwik Tracking API. This REST API allows to record Visitor and Events data in Piwik using any programming language. This Tracking API is different from the Analytics API.

Note: This doc is aimed at developers who are not using Javascript, PHP or Java. For JS, PHP and Java languages, there is already a client available. See the main documentation about Piwik Tracking API.

Tracking API endpoint

To track page views, events, visits, you have to send a HTTP request to your Tracking REST API endpoint: http://your-piwik-domain.tld/piwik.php

Tracking API reference

This section explains the various HTTP GET parameters that you can set to the Tracking API request to ensure your data is as complete and useful as possible. Some of these fields will not be available in your app / software which is expected: only a few parameters are required.

Note: all parameters values that are strings (such as ‘url’, ‘action_name’, etc.) must be URL encoded.

• Required and recommended parameters
  • idsite (required) — Defines the numeric Website ID being tracked
  • rec (required) — The parameter &rec=1 is required to enable tracking.
  • url (required) — The full URL for the current action.
  • action_name (recommended) — The custom Page title used to build the Piwik report Actions>Page Titles. It is possible to use slashes / to set one or several categories for this action. For example, ‘Help / Feedback’ will create the Action “Feedback” in the category “Help”.
  • _id (recommended) – The unique user id, must be a 16 characters hexadecimal string. It is important to always set the same _id values for a given user. Typically you would need a way to persist this value for your user — for example using Sessions or a a new field in your “users” table in your DB. If this value is not set Piwik will still work, but unique visitors tracking might be less accurate.
  • rand (recommended) — A random parameter, for example a random number generated before each request — this is useful to avoid the tracking request being cached by the browser or a proxy.
  • apiv (recommended) – The parameter &apiv=1 defines the api version you want to use.
• Optional visitor info — we recommend to set these values if they are available and relevant to your use case.
  • urlref — The full Referrer URL. This is used to populate the “Referrers” report (Websites, Search engines and keywords)
  • _cvar — Visit scope custom variables. This is a string JSON encoded of the custom variable array (see below for an example value).
  • _idvc — The current count of visits for this visitor. To set this value correctly, it would be required to store the value for each visitor in your application (using Sessions or persisting in your DB). Then you would manually increment by one on each new visit or “session”, depending on how you choose to defined a visit. This value is used to populate the report “Visitors > Engagement > Visits by visit number”.
  • _viewts — The UNIX timestamp of the time of the previous visit by this visitor. This parameter is used to populate the report “Visitors > Engagement > Visits by days since last visit”
  • _idts — The UNIX timestamp of the time of the first visit by this visitor. This could be set to the date where the user first started using your sofware/app, or when the user created his account. This parameter is used to populate the report “Goals > Days to Conversion”
  • _rcn — The Campaign name (see Tracking Campaigns). Used to populate report Referrers > Campaigns. Note: _rcn value will only be used for the first pageview of a given visitor.
  • _rck — The Campaign Keyword (see Tracking Campaigns). Used to populate report Referrers > Campaigns (clicking on a campaign loads all keywords for this campaign). Note: _rck value will only be used for the first pageview of a given visitor.
  • res — The resolution of the device, eg 1280×1024
  • h — The current hour – local time
  • m — The current minute – local time
  • s — The current second – local time
  • ua — This value is the User-Agent HTTP header string is used by Piwik to detect Operating System and browser used.
    Note: Alternatively you can set the User-Agent HTTP header instead of using the &ua= parameter.
  • lang — This value is the Accept-Language HTTP header, which lets Piwik detect user country (based on language) if GeoIP is not enabled.
    Note: Alternatively you can set the Accept-Language HTTP header instead of using the &lang= parameter.
• Optional action/event info — we recommend to set these values if they are available and relevant to your use case.
  • cvar — Page scope custom variables.This is a string JSON encoded of the custom variable array (see below for an example value)
  • link — An external URL the user has opened. We recommend to also set the ‘url’ parameter to this same value.
  • download — URL the user has downloaded. We recommend to also set the ‘url’ parameter to this same value.
  • search — The Site Search keyword. When specified, the request will not be tracked as normal pageview but will instead be tracked as a “Site Search” request.
    • search_cat -- when ‘search’ is specified, you can optionally specify a search category
    • search_count – when ‘search’ is specified, we also recommend to set the search_count to the number of search results displayed in the page. Piwik will then specifically report “No Result Search Keyword”, ie. keywords that were tracked with &search_count=0
  • idgoal — The request will trigger a conversion for the specified Goal
  • revenue — Defines a monetary revenue for the current goal conversion. Only used if “idgoal” is specified in the request.
  • gt_ms — Average generation time, in milliseconds. This value is used to process the “Avg. generation time” column, in the Page URL and Page Title reports, as well as a site wide running average of the speed of all pageviews. Note: when using the Javascript tracker this value is set to (Time for server to generate response + Time for client to download response).
• Special parameters requiring authentication via token_auth
  The following parameters require that you set &token_auth= to your token_auth value. The token_auth must be either the Super User token_auth, or a user with “admin” permission for this website ID.
  • token_auth — 32 characters to authenticate the API request
  • cip — (requires token_auth to be set) defines the visitor IP — ipv4 and ipv6 notations supported.
  • cdt — (requires token_auth to be set) defines the date & time to record the visit to. This is useful to record visits and page views in the past. The expected format is: 2011-04-05%2000%3A11%3A42 which is the URL encoded string of: 2011-04-05 00:11:42
    Note: if you record data in the past, you will need to force Piwik to re-process reports for the past dates: see this FAQ for more information
  • cid — (requires token_auth to be set) defines the visitor ID for this request. You must set this value to exactly a 16 character hexadecimal string (containing only characters 01234567890abcdefABCDEF). When specified, the Visitor ID will be “enforced”. This means that if there is no recent visit with this visitor ID, a new one will be created. If a visit is found in the last 30 minutes with your specified Visitor Id, then the new action will be recorded to this existing visit.

  Specifying any of the user’s Geo location details requires token_auth to be set:

  • country — The two letter country code of the visitor, eg fr, de, us.
  • region — The two letter region code as defined by MaxMind’s GeoIP databases. See here for a list of them for every country (the region codes are located in the second column to the left of the region name and to the right of the country code).
  • city — The name of the city the visitor is located in.
  • lat — The visitor’s latitude, eg 22.456.
  • long — The visitor’s longitude, eg 22.456.

Note about tracking bots

By default Piwik does not track bots. If you use the REST Tracking API, you might want to also enable tracking of these requests that Piwik detect as both (using basic user agent matching or IPs from known bots). To enable Bot Tracking in Piwik, set the parameter &bots=1 to the piwik.php request.

Example HTTP request to Piwik Tracking API

Here is an example of a real tracking request, as done by Piwik Mobile app for the anonymous Piwik Mobile Analytics.

http://piwik-server/piwik.php?_cvar={“1″:["OS","iphone 5.0"],”2″:["Piwik Mobile Version","1.6.2"],”3″:["Locale","en::en"],”4″:["Num Accounts","2"]}&action_name=View settings&url=http://mobileapp.piwik.org/window/settings &idsite=8876&rand=351459&h=18&m=13&s=3 &rec=1&apiv=1&cookie= &urlref=http://iphone.mobileapp.piwik.org&_id=af344a398df83874 &_idvc=19&res=320×480&

Explanation: this URL has custom variables for the OS, Piwik version, # Accounts created, tracks an event “View settings” with a fake URL, records the screen resolution, and also includes _id, a custom unique ID generated to ensure all requests for the same Mobile App user will be recorded for the same visit in Piwik.

Debugging the Tracking API requests

To verify that your data is being tracked properly, you can enable debug logging in the Piwik tracking file piwik.php.

Tracking requests will then output the tracking logs rather than displaying a 1*1 transparent GIF beacon.

Follow these simple steps to enable debug logging in piwik.php:

1. In the file path/to/piwik/piwik.php, you can set $GLOBALS['PIWIK_TRACKER_DEBUG'] = true;
2. Look at the http requests that are sent to Piwik
   • If the requests take place in the browser, you can use a tool like Firebug Net panel to see all requests to “piwik.php”
   • If the requests are triggered from your app or software directly, you can output or log the Tracking URL piwik.php?… and manually load it to view the logging messages.

Advanced: Bulk Tracking Requests

What is Bulk Tracking?

Some applications such as the Piwik log importer, have to track many visits, sometimes tens, hundreds, thousands or even more all at once. Tracking these requests with one HTTP request per visit or action can result in enormous delays because there is a delay of several milliseconds to establish the HTTP connection. Using the bulk tracking feature, however, these requests can be sent all at once as a POST request, making your application far more efficient.

How to Track several pages with one request?
To send a bulk tracking request, you must POST a JSON object to the Piwik tracking endpoint. The object should contain the following properties:

• token_auth – token_auth can be found in the API page. Provide at least Admin or Super User permission to use
• requests An array of individual tracking requests. Each tracking request should be the query string you’d send if you were going to track that action individually.

Example Data

{
   "requests": [
      "?idsite=1&url=http://example.org&action_name=Test bulk log Pageview&rec=1",
      "?idsite=1&url=http://example.net/test.htm&action_name=Another bul k page view&rec=1"
   ],
   "token_auth": "33dc3f2536d3025974cccb4b4d2d98f4"
}

Example Bulk Tracking Call using CURL
Here is an example POST request passing the JSON containing the token and the requests.
$ curl -i -X POST -d '{"requests":["?idsite=1&url=http://example.org&action_name=Test bulk log Pageview&rec=1","?idsite=1&url=http://example.net/test.htm&action_name=Another bul
k page view&rec=1"],"token_auth":"33dc3f2536d3025974cccb4b4d2d98f4"}' http://piwik.example.com/piwik.php
#This will track 2 requests using only 1 http request to Piwik.


More information
See the doc about Piwik Tracking API for more information. If you’re stuck, ask in the forums (after making a search) or hire a Piwik expert.

If you have any feedback or suggestion about this doc let us know in the comment field below.