Go Back

Reporting API

June 12, 2018

The document below outlines key concepts of the API including functions, documents, and parameters that you can play with. Feel free to pull all your relevant data from Piwik PRO into your custom apps, like reporting dashboards, BI software, data warehouses, etc.

API Request

A request to the Piwik PRO Reporting API is composed of standard and additional API parameters.

Standard API Parameters

idSite

An array containing integer id(s) of your website or websites

  • idSite=1 and idSite=1,4,5,6 are also permitted
  • set idSite=all if you want to get data for all websites associated with your Piwik PRO account
  • period

    The period you request the statistics for: can be a day, week, month, year, or range. All reports are returned for the dates based on the website’s time zone.

  • day returns data for a given day.
  • week returns data for the week that contains the specified ‘date’
  • month returns data for the month that contains the specified ‘date’
  • year returns data for the year that contains the specified ‘date’
  • range returns data for the specified ‘date’ range.
  • Example: to request a report for the range Jan 1st to Jan 31th you would write &period=range&date=2017-01-01,2017-01-31

    date

    A reference to a specific date comes in standard format = YYYY-MM-DD but can be used with “magic keywords” like today or yesterday. These are relative to the website timezone.

    Example: for a website with UTC+12 timezone, “date=today” for an API request at 5PM UTC on 2017-01-01 will return the reports for 2017-01-02.

    range of date

    Refers to the last or previous amount of periods from the actual date, including today and is relative to the website timezone. Here are some examples of the syntax:

    Example: &date=last5&period=day

    This returns an entry for each of the last 5 days including today.

    Example: &date=last52&period=week

    This returns an entry for each of the 52 weeks before the current week.

    Example: &date=2017-01-01,2017-01-31&period=day

    This returns an entry of the sum of the data for the specified date range.

    The “date” parameter supports the following special keywords:

  • lastX
  • previousX
  • YYYY-MM-DD,YYYY-MM-DD
  • YYYY-MM-DD,today
  • YYYY-MM-DD,yesterday
  • segment

    This parameter refers to the Custom Segment of traffic you want to use to filter your Piwik PRO reports.

    Example: &segment=referrerName==facebook.com

    This returns the requested API report, processed for users coming just from facebook.com.
    Example: &segment=&referrerName==facebook.com,referrerName==twitter.com,referrerName==Google

    This returns the requested API report, processed for users coming from facebook.com OR twitter.com OR Google.

    Logical operators are handled here with commas and semicolons, where comma means OR and semicolon means AND. To form an alternative clause you would write

    referrerName==facebook.com,referrerName==twitter.com

    Which Is equal to:
    facebook.com OR twitter.com

    To form a conjunction of alternatives, you would write:

    referrerName==facebook.com,referrerName==twitter.com;referrerName==Google,country=US

    Which is equivalent to the following:

    (referrer facebook.com OR twitter.com) AND (referrer Google OR country US)

    To check all available options, please refer to the segmentation documentation, where you will find a list of dimensions and metrics, example values for each and more information on the custom segment parameter.

    Format

    Defines the format of the output of your API call, and may take one of the following values:

  • xml (outputs xml file)
  • json (outputs json file, if you want to do cross domain request in ajax and get json data, you can wrap the json data around a function call by using the jsoncallback parameter)
  • csv (outputs comma-separated values file)
  • tsv (outputs tab-separated values file, better option than CSV for further work with Excel)
  • html (outputs html file)
  • php (please note that when you export in PHP format, the output is serialized by default, you can set additional parameter serialize=0 to get the raw php data structure, here you can also have a visual output of the data by setting prettyDisplay=1 parameter).
  • rss (only when date is a range for example date=last10 or date=previous15)
  • original (used to fetch the original PHP data structure, useful when you call the Piwik API internally using the PHP code)