API/Reference

API reference

  1. API reference
    1. Some examples first
    2. Standard parameters
    3. Make an authenticated call
    4. Other parameters
    5. Passing an Array Parameter
    6. Methods
    7. See also

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
    • you can also specify a list of idSites comma separated, eg. idSite=1,4,5,6
    • if you want to get data for all websites, set idSite=all
  • 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 (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
    • 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).
  • the idSubtable is used to request a subtable of a given row. In Piwik, some rows are linked to a sub table. For example, each row in the Referers.getSearchEngines response have a "idsubdatatable" field. This integer idsubdatatable is the idSubtable of the table that contains all keywords for this search engine. You can then request the keywords for this search engine by calling Referers.getKeywordsFromSearchEngineId with the parameter idSubtable=X (replace X with the idsubdatatable value found in the Referers.getSearchEngines response, for the search engine you are interested in).

Passing an Array Parameter

Some parameters can optionally accept arrays. For example, the urls parameter of SitesManager.addSite, SitesManager.addSiteAliasUrls, and SitesManager.updateSite allow for an array of urls to be passed. To pass an array add the bracket operators and an index to the parameter name in the get request. So, to call SitesManager.addSite with two urls you would use the following array:

http://piwik.org/demo/?module=API&method=SitesManager.addSite&siteName=new%20example%20website&urls[0]=http://example.org&urls[1]=http://example-alias.org

Methods

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

Module Actions

- Actions.getPageUrls (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.getPageTitles (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 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, columns = 'Array') [ 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.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 ]
- VisitsSummary.getVisitsConverted (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.getSumVisitsLengthPretty (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.get (idSite, period, date, columns = 'Array') [ 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 ]
- VisitFrequency.getConvertedVisitsReturning (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 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 = '') [ No example available ]
- UsersManager.updateUser (userLogin, password = '', email = '', alias = '') [ No example available ]
- 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) [ No example available ]
- UsersManager.getTokenAuth (userLogin, md5Password) [ No example available ]

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) [ No example available ]
- SitesManager.deleteSite (idSite) [ No example available ]
- SitesManager.addSiteAliasUrls (idSite, urls) [ No example available ]
- SitesManager.updateSite (idSite, siteName, urls = '') [ No example available ]

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 ]

Module ExampleAPI

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

Module LanguagesManager

- LanguagesManager.isLanguageAvailable (languageCode) [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.getAvailableLanguages () [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.getAvailableLanguagesInfo () [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.getAvailableLanguageNames () [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.getTranslationsForLanguage (languageCode) [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.getLanguageForUser (login) [ No example available ]
- LanguagesManager.setLanguageForUser (login, languageCode) [ No example available ]
- LanguagesManager.getLanguageForSession () [ Example in XML, PHP, Json, Csv, Basic html ]
- LanguagesManager.setLanguageForSession (languageCode) [ Example in XML, PHP, Json, Csv, Basic html ]

Module DBStats

- DBStats.getDBStatus () [ Example in XML, PHP, Json, Csv, Basic html ]
- DBStats.getTableStatus (table, field = '') [ No example available ]
- DBStats.getAllTablesStatus () [ Example in XML, PHP, Json, Csv, Basic html ]

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 Goals

- Goals.getGoals (idSite) [ Example in XML, PHP, Json, Csv, Basic html ]
- Goals.addGoal (idSite, name, matchAttribute, pattern, patternType, caseSensitive, revenue) [ No example available ]
- Goals.updateGoal (idSite, idGoal, name, matchAttribute, pattern, patternType, caseSensitive, revenue) [ No example available ]
- Goals.deleteGoal (idSite, idGoal) [ No example available ]
- Goals.getConversionRateReturningVisitors (idSite, period, date, idGoal = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Goals.getConversionRateNewVisitors (idSite, period, date, idGoal = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Goals.get (idSite, period, date, idGoal = '', columns = 'Array') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Goals.getConversions (idSite, period, date, idGoal = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Goals.getConversionRate (idSite, period, date, idGoal = '') [ Example in XML, PHP, Json, Csv, Basic html , RSS of the last 10 days, 5 weeks, XML of the last 10 days ]
- Goals.getRevenue (idSite, period, date, idGoal = '') [ 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, typeReferer = '') [ 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, expanded = '') [ 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, expanded = '') [ 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, expanded = '') [ 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, expanded = '') [ 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.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 ]

See also

Find other documentation on Piwik web analytics API