HTTP API

Tracking HTTP API allows sending to analytics information about Visitors page views, events and visits.

Deprecated since version 5.5.1: Endpoint /piwik.php is moved to /ppms.php. The old endpoint still works, but its support will be disabled at some point.

POST /ppms.php

Tracking endpoint

Endpoint tracking actions (page views, events and visits).

In addition to standard tracking parameters from GET request, it is also able to handle bulk requests.

Status Codes:
GET /ppms.php

Tracking endpoint

Endpoint tracking actions (page views, events and visits).

Query Parameters:
 
  • idsite (string) – Application ID (previously Website ID).
  • rec (integer) – Consent to tracking (value “1” allows it).
  • url (string) – URL of action.
  • action_name (string) –

    Recommended Name of action.

    It is possible to categorize actions by preceding them with one or more category names separated by a slash character (/).

  • _id (string) –

    Recommended Visitor ID.

    It allows you to use the application identifier of a Visitor instead of a default identifier generated by the analytics. See: [Recognizing Visitors](https://help.piwik.pro/analytics/recognizing-visitors/).

  • rand (string) –

    Recommended Cache buster.

    Its value should be unique for every request to make sure that the request is sent to server and not read from a cache. Value can be random or sequential (e.g. UNIX timestamp). It is especially useful if the visitor is behind some kind of caching proxy.

  • urlref (string) –

    HTTP referrer.

    The URL of the previous page that linked to current one.

  • _cvar (string) –

    [Custom variables](https://help.piwik.pro/analytics/custom-variables/) set on the visit scope.

    Format: Object serialized with JSON:

    • key - (string) Custom variable ID
    • value - Array with: - (string) Custom variable name, max length: 200 characters - (string) Custom variable value, max length: 200 characters
  • cvar (string) –

    [Custom variables](https://help.piwik.pro/analytics/custom-variables/) set on the page scope.

    Format: Object serialized with JSON:

    • key - (string) Custom variable ID
    • value - Array with: - (string) Custom variable name, max length: 200 characters - (string) Custom variable value, max length: 200 characters
  • _idvc (integer) –

    Visit counter.

    It sets the visit number of the visitor. It should be used when the application already tracks how many times the visitor used it and you want to override default visit counter.

    Used in Visitors > Engagement > Visits by visit number report.

  • _viewts (integer) –

    Time of previous visit.

    Used in Visitors > Engagement > Visits by days since last visit report.

  • _idts (integer) –

    Time of first visit.

    Used in Goals > Days to Conversion report.

  • res (string) – Resolution of the visitor’s device in pixels.
  • h (integer) – Hour when the request was made in the visitor’s local time.
  • m (integer) – Minute when the request was made in the visitor’s local time.
  • s (integer) – Second when the request was made in the visitor’s local time.
  • ua (string) –

    User-Agent browser value. It can be used to override value send in request HTTP header.

    It is used to detect Visitors browser and operating system.

  • lang (string) –

    Accept-Language browser value. It can be used to override value send in request HTTP header.

    It’s used to guess Visitors country when GeoIP is not able to determine it.

  • uid (string) –

    User ID.

    Can be used to identify Visitor by the application (e.g. login name, email address or internal user ID). See: [Recognizing Visitors](https://help.piwik.pro/analytics/recognizing-visitors/).

    It allows merging visits across different devices (e.g. laptop, tablet and smartphone).

  • cid (string) –

    Configuration ID.

    Semi-unique hash generated for the visitor’s browser (based on configuration and installed plugins). This parameter overwrites visitor’s config_id. For further explanation please read the following article: [Recognizing Visitors](https://help.piwik.pro/analytics/recognizing-visitors/) - the Fingerprint section.

  • new_visit (integer) – Force start of new visit when value is 1.
  • dimensionID (string) –

    [Custom dimension](https://help.piwik.pro/analytics/custom-dimensions/) value for specific ID. Assigns arbitrary value to specific visit or action dimension.

    ID in the parameter name should be replaced with its integer value (e.g. dimension1, dimension2, dimension999).

  • link (string) – External URL opened by the Visitor. It is recommended to set url parameter to same value.
  • download (string) – URL of downloaded file.
  • search (string) –

    Internal search query. This is used to track what was searched by a visitor in the application. See: [Site search](https://help.piwik.pro/analytics/site-search/).

    Requests using this parameter are excluded from the general page view statistics.

  • search_cat (string) –

    Internal search category. This is used to track if visitor specified a category during a search of the application. See: [Site search](https://help.piwik.pro/analytics/site-search/).

    Requests using this parameter are excluded from the general page view statistics.

  • search_count (integer) –

    Number of results of internal search.

    Used to track number of results found by the visitor.

  • pv_id (string) –

    Unique page view ID generated when the page is loaded.

    This is used to identify further actions performed during that page view (e.g. events) as part of single page view.

  • idgoal (integer) –

    Goal ID. Signifies that a goal has been reached and tracks its conversion.

    Value 0 is reserved for Ecommerce cart tracking.

  • revenue (number) –

    Revenue value of achieved goal.

    Currency of the value does not matter, but only one should be used by the application (e.g. USD).

  • ec_id (string) – Ecommerce order ID.
  • ec_items (string) –

    Ecommerce order item list.

    Each item on the list must contain:

    • sku: string Stock keeping unit.
    • name: string Name of item.
    • category: string Category of item.
    • price: number Price of item. Currency of this value does not matter, but only one should be used by the application (e.g. USD).
    • quantity: integer Quantity of item.
  • ec_st (number) –

    Ecommerce order sub-total (order cost without shipping).

    Currency of the value does not matter, but only one should be used by the application (e.g. USD).

  • ec_tx (number) –

    Ecommerce order tax.

    Currency of the value does not matter, but only one should be used by the application (e.g. USD).

  • ec_sh (number) –

    Ecommerce order shipping.

    Currency of the value does not matter, but only one should be used by the application (e.g. USD).

  • ec_dt (number) –

    Ecommerce order discount.

    Currency of the value does not matter, but only one should be used by the application (e.g. USD).

  • _ects (integer) –

    Time of last Ecommerce order.

    Used in Days since last order report.

  • gt_ms (integer) –

    Page generation and load time in milliseconds.

    Used for example in Page speed report.

  • cs (string) –

    Page charset.

    Used to decode text data sent in request.

  • cookie (integer) – Status of Cookie capability in Visitor browser (value “1” indicates that it is enabled).
  • fla (integer) – Status of Flash plugin in Visitor browser (value “1” indicates that it is installed).
  • java (integer) – Status of Java plugin in Visitor browser (value “1” indicates that it is installed).
  • dir (integer) – Status of Adobe Director plugin in Visitor browser (value “1” indicates that it is installed).
  • qt (integer) – Status of QuickTime plugin in Visitor browser (value “1” indicates that it is installed).
  • realp (integer) – Status of RealPlayer plugin in Visitor browser (value “1” indicates that it is installed).
  • pdf (integer) – Status of PDF plugin in Visitor browser (value “1” indicates that it is installed).
  • wma (integer) – Status of Windows Media Player plugin in Visitor browser (value “1” indicates that it is installed).
  • gears (integer) – Status of (Google) Gears plugin in Visitor browser (value “1” indicates that it is installed).
  • ag (integer) – Status of Silverlight plugin in Visitor browser (value “1” indicates that it is installed).
  • e_c (string) – Custom event category.
  • e_a (string) – Custom event action.
  • e_n (string) – Custom event name.
  • e_v (number) – Custom event value.
  • c_n (string) – Content name.
  • c_p (string) – Content piece.
  • c_t (string) – Content target.
  • c_i (string) – Content interaction.
  • send_image (integer) –

    Request response content:

    • 0 - HTTP 204 [No content]
    • 1 - HTTP 200 [1 pixel GIF]
  • bots (integer) –

    Bots tracking:

    • 0 - disabled
    • 1 - enabled
  • token_auth (string) – Authentication token used by SuperUser or Admin in requests using parameters that require it.
  • cip (string) –

    Override IP.

    This parameter requires authentication using the token_auth parameter.

  • cdt (string) –

    Override request time. You can use it when importing archive HTTP logs.

    If time set this way is from the future, override will be ignored and the current time will be used instead.

    If this parameter is used it is necessary to re-process the report for time range containing overridden time, otherwise such requests will not be included in the reports.

    It is possible to override request time without authentication if the difference between set time and current one is less than or equal to 24h. Setting time earlier than this requires authentication using the token_auth parameter.

  • country (string) –

    Override country.

    This parameter requires authentication using the token_auth parameter.

  • region (string) –

    Override region.

    Format of [region codes](https://www.maxmind.com/download/geoip/misc/region_codes.csv) is defined in [MaxMind’s](https://www.maxmind.com/) GeoIP database.

    This parameter requires authentication using the token_auth parameter.

  • city (string) –

    Override city.

    This parameter requires authentication using the token_auth parameter.

  • lat (number) –

    Override latitude.

    This parameter requires authentication using the token_auth parameter.

  • lon (number) –

    Override longitude.

    This parameter requires authentication using the token_auth parameter.

  • uia (integer) –

    Allows to track user anonymously.

    • 1 - all IP bytes will be masked (0.0.0.0), no GeoIP data will be stored and visits won’t be matched by the fingerprinting process
    • 0 - all available visitor data will be enriched if anonymized previously
Status Codes: