The Tracking HTTP API

To track page views, events, visits, you have to send a HTTP request to your Tracking HTTP API endpoint, for example, http://your-piwik-domain.tld/piwik.php with the correct query parameters set.

Supported Query Parameters

This section lists the various query parameters that are supported by the Tracking API. The data for some of these fields will not be available in your app / software which is expected, but you should provide as much information as you can.

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

Tracking Bots

By default Piwik does not track bots. If you use the Tracking HTTP API directly, you may be interested in tracking bot requests. To enable Bot Tracking in Piwik, set the parameter &bots=1 in your requests to piwik.php.

Example Tracking Request

Here is an example of a real tracking request used by the Piwik Mobile app when anonymously tracking Mobile App usage:

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= &idsite=8876&rand=351459&h=18&m=13&s=3 &rec=1&apiv=1&cookie= &urlref= &_idvc=19&res=320×480&

Note: for clarity, parameter values are not URL encoded in this example.

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

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 due to the amount of time it takes to send an HTTP request, Using the bulk tracking feature, however, these requests can be sent all at once making the application far more efficient.

To send a bulk tracking request, an HTTP POST must be made with a JSON object to the Piwik tracking endpoint. The object must contain the following properties:

Example Requests

This is an example of the payload of a bulk tracking request:

   "requests": [
      "?idsite=1&url= bulk log Pageview&rec=1",
      "?idsite=1&url= bul k page view&rec=1"
   "token_auth": "33dc3f2536d3025974cccb4b4d2d98f4"

Here is the command to send this request to Piwik using curl (without the token_auth which is optional in this case):

curl -i -X POST -d '{"requests":["?idsite=1&url= bulk log Pageview&rec=1","?idsite=1&url= bulk page view&rec=1"]}'

This will track two actions using only one HTTP request to Piwik.

Debugging the Tracker

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 log messages rather than displaying a 1*1 transparent GIF beacon.

Follow these steps to enable and view debug logging for the tracker:

  1. In your config file path/to/piwik/config/config.ini.php, write the following:

    [Tracker] debug = 1

  2. Look at the HTTP requests that are sent to Piwik.

    • If the requests take place in a browser, you can use a tool like the Firebug to see all requests to piwik.php.
    • If the requests are triggered from your app or software directly, you can output or log the output of tracking requests and to view the debug messages.

Learn more