API reference

Some examples first

  • XML of the visits of the last 10 days, one entry per day

http://piwik.org/demo/?module=API&method=VisitsSummary.getVisits&idSite=1&period=day&date=last10&format=xml

  • XML containing keywords from the last 3 weeks, one entry per week

http://piwik.org/demo/?module=API&method=Referers.getKeywords&idSite=1&period=week&date=last3&format=xml

  • XML containing the keywords from the last 3 days which match the pattern "piwik"

http://piwik.org/demo/?module=API&method=Referers.getKeywords&idSite=1&period=day&date=last3&format=xml&filter_column=label&filter_pattern=piwik

  • RSS feed containing the top 30 keywords for the last 3 weeks, ordered by the number of actions people did when coming from these keywords

http://piwik.org/demo/?module=API&method=Referers.getKeywords&idSite=1&period=week&date=last3&format=rss&filter_limit=30&filter_sort_column=3

Standard parameters

  • idSite ; the integer id of your website (eg. idSite=1)
  • period ; the period you request the statistics on: day or week or month or year
  • date
    • standard format = YYYY-MM-DD
    • magic keywords = today or yesterday
    • range of dates
      • lastX for the last X periods including today (eg &date=last10&period=day would return an entry for each of the last 10 days including today)
      • previousX returns the last X periods before today (eg. &date=last52&period=week will return an entry for each of the 52 weeks before this week)
      • YYYY-MM-DD,YYYY-MM-DD for every day in the date range
  • format ; defines the format of the output
    • xml
    • json
    • csv
    • html
    • php ; when you export in PHP format it is serialized by default (set serialize=0 to get the raw php data structure). You can have a visual output of the data by setting prettyDisplay=1
    • rss (when date is a range for example date=last10 or date=previous15)
    • original ; you get the original data without any conversion (rarely useful)

Make an authenticated call

In the example above, the request works because the statistics are public (the anonymous user has a view access to the website). Usually you don't want your statistics to be public.

  • when you go in your piwik installation you are requested to login
  • when you call the API over http you need to authenticate yourself

This is done by adding a secret parameter in the URL. This parameter is as secret as your login and password!

You can get this token in the Manage Users admin area.

Then you simply have to add the parameter &token_auth=YOUR_TOKEN at the end of your API call URL.

Other parameters

More documentation will come, but here is an overview of the parameters you can add to any request returning data tables:

  • (optional) the filter_offset ; defines the offset of the starting row being returned
  • (optional) the filter_limit ; defines the number of rows to be returned
  • (optional) the filter_pattern ; defines the text we want to search for in the filter_column. Only the row with the given column matching the pattern will be returned.
  • (optional) the filter_column ; defines the column that we want to search for a text (see filter_pattern).
  • (optional) the filter_sort_order ; defines the order of the results, asc or desc
  • (optional) the filter_sort_column ; defines to column to be sorted by
  • (optional) the filter_excludelowpop ; defines the column to use for the threshold of value filter_excludelowpop_value ; only the columns with a value greater than filter_excludelowpop_value will be returned
  • (optional) the filter_excludelowpop_value defines the minimum value for the filter_excludelowpop column
  • (optional) the filter_column_recursive ; defines the column to be searched for when recursively searching for a pattern filter_pattern_recursive
  • (optional) the filter_pattern_recursive ; defines the text we are searching for. Only the matching rows are returned. This filter is applied to recursive tables (Actions / Downloads / Outlinks tables)
  • (optional) the disable_generic_filters ; if set to 1, all the generic filters above will not be applied (useful because the filters above are applied all the time with default values. Sometimes this is annoying so we want to disable this behaviour)
  • (optional) the disable_queued_filters ; if set to 1, all the filters that are mostly presentation filters (replace a column name, apply callbacks on the column to add new information such as the browser icon URL, etc.) will not be applied (rarely useful).

Methods

We will add the documentation of every method soon, but hopefully their name are already quite descriptive.

Module Actions

- Actions.getActions (idSite, period, date, expanded = '', idSubtable = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Actions.getDownloads (idSite, period, date, expanded = '', idSubtable = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Actions.getOutlinks (idSite, period, date, expanded = '', idSubtable = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module Referers

- Referers.getRefererType (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getKeywords (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getSearchEnginesFromKeywordId (idSite, period, date, idSubtable) [ No example available ]
- Referers.getSearchEngines (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getKeywordsFromSearchEngineId (idSite, period, date, idSubtable) [ No example available ]
- Referers.getCampaigns (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getKeywordsFromCampaignId (idSite, period, date, idSubtable) [ No example available ]
- Referers.getWebsites (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getUrlsFromWebsiteId (idSite, period, date, idSubtable) [ No example available ]
- Referers.getPartners (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getUrlsFromPartnerId (idSite, period, date, idSubtable) [ No example available ]
- Referers.getNumberOfDistinctSearchEngines (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctKeywords (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctCampaigns (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctWebsites (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctWebsitesUrls (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctPartners (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Referers.getNumberOfDistinctPartnersUrls (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module UserSettings

- UserSettings.getResolution (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getConfiguration (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getOS (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getBrowser (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getBrowserType (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getWideScreen (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserSettings.getPlugin (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module UserCountry

- UserCountry.getCountry (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserCountry.getContinent (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- UserCountry.getNumberOfDistinctCountries (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module VisitsSummary

- VisitsSummary.get (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getVisits (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getUniqueVisitors (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getActions (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getMaxActions (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getSumVisitsLength (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitsSummary.getBounceCount (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module VisitFrequency

- VisitFrequency.getSummary (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitFrequency.getVisitsReturning (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitFrequency.getActionsReturning (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitFrequency.getMaxActionsReturning (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitFrequency.getSumVisitsLengthReturning (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitFrequency.getBounceCountReturning (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module VisitTime

- VisitTime.getVisitInformationPerLocalTime (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitTime.getVisitInformationPerServerTime (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module VisitorInterest

- VisitorInterest.getNumberOfVisitsPerVisitDuration (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- VisitorInterest.getNumberOfVisitsPerPage (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

Module UsersManager

- UsersManager.getUsers () [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getUsersLogin () [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getUsersSitesFromAccess (access) [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getUsersAccessFromSite (idSite) [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getSitesAccessFromUser (userLogin) [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getUser (userLogin) [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getUserByEmail (userEmail) [ No example available ]
- UsersManager.addUser (userLogin, password, email, alias = '') [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.updateUser (userLogin, password = '', email = '', alias = '') [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.deleteUser (userLogin) [ No example available ]
- UsersManager.userExists (userLogin) [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.userEmailExists (userEmail) [ No example available ]
- UsersManager.setUserAccess (userLogin, access, idSites = '') [ Example in XML, PHP, Json, Csv, Basic html ]
- UsersManager.getTokenAuth (userLogin, passwordMd5ied) [ Example in XML, PHP, Json, Csv, Basic html ]

Module SitesManager

- SitesManager.getJavascriptTag (idSite, piwikUrl = '', actionName = '') [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSiteFromId (idSite) [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSiteUrlsFromId (idSite) [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getAllSitesId () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesWithAdminAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesWithViewAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesWithAtLeastViewAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesIdWithAdminAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesIdWithViewAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.getSitesIdWithAtLeastViewAccess () [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.addSite (siteName, urls) [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.deleteSite (idSite) [ No example available ]
- SitesManager.addSiteAliasUrls (idSite, urls) [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.replaceSiteUrls (idSite, urls) [ Example in XML, PHP, Json, Csv, Basic html ]
- SitesManager.updateSite (idSite, siteName, urls) [ Example in XML, PHP, Json, Csv, Basic html ]

Module ExamplePlugin

- ExamplePlugin.getAnswerToLife () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getGoldenRatio () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getObject () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getNull () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getDescriptionArray () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getCompetitionDatatable () [ Example in XML, PHP, Json, Csv, Basic html ]
- ExamplePlugin.getMoreInformationAnswerToLife () [ Example in XML, PHP, Json, Csv, Basic html ]

Module Provider

- Provider.getProvider (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Provider.getProviderBlob (idSite, period, date) [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]

See also

Find other documentation on Piwik web analytics API