Date range: 2024-03-28
Date
Period





API quick documentation

All the data in Piwik is available through simple APIs. This plugin is the web service entry point, that you can call to get your Web Analytics data in xml, json, php, csv, etc.

For more information about the Piwik APIs, please have a look at the Introduction to Piwik API and the Piwik API Reference .

User authentication

If you want to request data within a script, a crontab, etc. you need to add the parameter to the API calls URLs that require authentication.
&token_auth=anonymous
This token_auth is as secret as your login and password, do not share it!

Quick access to APIs

API
Actions
Annotations
CustomVariables
Dashboard
ExampleAPI
ExamplePlugin
Goals
ImageGraph
LanguagesManager
Live
MobileMessaging
MultiSites
Overlay
Provider
Referrers
SEO
ScheduledReports
SegmentEditor
SitesManager
Transitions
UserCountry
UserSettings
UsersManager
VisitFrequency
VisitTime
VisitorInterest
VisitsSummary

Module API

This API is the Metadata API: it gives information about all other available APIs methods, as well as providing human readable and more complete outputs than normal API methods. Some of the information that is returned by the Metadata API:
  • the dynamically generated list of all API methods via "getReportMetadata"
  • the list of metrics that will be returned by each method, along with their human readable name, via "getDefaultMetrics" and "getDefaultProcessedMetrics"
  • the list of segments metadata supported by all functions that have a 'segment' parameter
  • the (truly magic) method "getProcessedReport" will return a human readable version of any other report, and include the processed metrics such as conversion rate, time on site, etc. which are not directly available in other methods.
  • the method "getSuggestedValuesForSegment" returns top suggested values for a particular segment. It uses the Live.getLastVisitsDetails API to fetch the most recently used values, and will return the most often used values first.
The Metadata API is for example used by the Piwik Mobile App to automatically display all Piwik reports, with translated report & columns names and nicely formatted values. More information on the Metadata API documentation page
- API.getPiwikVersion () [ Example in XML, Json, Tsv (Excel) ]
- API.getSettings () [ Example in XML, Json, Tsv (Excel) ]
- API.getDefaultMetricTranslations () [ Example in XML, Json, Tsv (Excel) ]
- API.getSegmentsMetadata (idSites = 'Array') [ Example in XML, Json, Tsv (Excel) ]
- API.getLogoUrl (pathOnly = '') [ Example in XML, Json, Tsv (Excel) ]
- API.getHeaderLogoUrl (pathOnly = '') [ Example in XML, Json, Tsv (Excel) ]
- API.getMetadata (idSite, apiModule, apiAction, apiParameters = 'Array', language = '', period = '', date = '', hideMetricsDoc = '', showSubtableReports = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- API.getReportMetadata (idSites = '', period = '', date = '', hideMetricsDoc = '', showSubtableReports = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- API.getProcessedReport (idSite, period, date, apiModule, apiAction, segment = '', apiParameters = '', idGoal = '', language = '', showTimer = '1', hideMetricsDoc = '', idSubtable = '', showRawMetrics = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- API.get (idSite, period, date, segment = '', columns = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- API.getRowEvolution (idSite, period, date, apiModule, apiAction, label = '', segment = '', column = '', language = '', idGoal = '', legendAppendMetric = '1', labelUseAbsoluteUrl = '1') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- API.getBulkRequest (urls) [ No example available ]
- API.getSuggestedValuesForSegment (segmentName, idSite) [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module Actions

The Actions API lets you request reports for all your Visitor Actions: Page URLs, Page titles (Piwik Events), File Downloads and Clicks on external websites. For example, "getPageTitles" will return all your page titles along with standard Actions metrics for each row. It is also possible to request data for a specific Page Title with "getPageTitle" and setting the parameter pageName to the page title you wish to request. Similarly, you can request metrics for a given Page URL via "getPageUrl", a Download file via "getDownload" and an outlink via "getOutlink". Note: pageName, pageUrl, outlinkUrl, downloadUrl parameters must be URL encoded before you call the API.
- Actions.get (idSite, period, date, segment = '', columns = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageUrls (idSite, period, date, segment = '', expanded = '', idSubtable = '', depth = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageUrlsFollowingSiteSearch (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageTitlesFollowingSiteSearch (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getEntryPageUrls (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getExitPageUrls (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageUrl (pageUrl, idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageTitles (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getEntryPageTitles (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getExitPageTitles (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getPageTitle (pageName, idSite, period, date, segment = '') [ No example available ]
- Actions.getDownloads (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getDownload (downloadUrl, idSite, period, date, segment = '') [ No example available ]
- Actions.getOutlinks (idSite, period, date, segment = '', expanded = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getOutlink (outlinkUrl, idSite, period, date, segment = '') [ No example available ]
- Actions.getSiteSearchKeywords (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getSiteSearchNoResultKeywords (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Actions.getSiteSearchCategories (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module Annotations

API for annotations plugin. Provides methods to create, modify, delete & query annotations.
- Annotations.add (idSite, date, note, starred = '0') [ No example available ]
- Annotations.save (idSite, idNote, date = '', note = '', starred = '') [ No example available ]
- Annotations.delete (idSite, idNote) [ No example available ]
- Annotations.get (idSite, idNote) [ No example available ]
- Annotations.getAll (idSite, date = '', period = 'day', lastN = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Annotations.getAnnotationCountForDates (idSite, date, period, lastN = '', getAnnotationText = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module CustomVariables

The Custom Variables API lets you access reports for your Custom Variables names and values.
- CustomVariables.getCustomVariables (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- CustomVariables.getCustomVariablesValuesFromNameId (idSite, period, date, idSubtable, segment = '') [ No example available ]
↑ Back to top

Module Dashboard

This API is the Dashboard API: it gives information about dashboards.
- Dashboard.getDashboards () [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module ExampleAPI

The ExampleAPI is useful to developers building a custom Piwik plugin. Please see the source code in in the file plugins/ExampleAPI/API.php for more documentation.
- ExampleAPI.getPiwikVersion () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getAnswerToLife () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getObject () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getSum (a = '0', b = '0') [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getNull () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getDescriptionArray () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getCompetitionDatatable () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getMoreInformationAnswerToLife () [ Example in XML, Json, Tsv (Excel) ]
- ExampleAPI.getMultiArray () [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module ExamplePlugin

API for plugin ExamplePlugin
- ExamplePlugin.getAnswerToLife (truth = '1') [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module Goals

Goals API lets you Manage existing goals, via "updateGoal" and "deleteGoal", create new Goals via "addGoal", or list existing Goals for one or several websites via "getGoals" If you are tracking Ecommerce orders and products on your site, the functions "getItemsSku", "getItemsName" and "getItemsCategory" will return the list of products purchased on your site, either grouped by Product SKU, Product Name or Product Category. For each name, SKU or category, the following metrics are returned: Total revenue, Total quantity, average price, average quantity, number of orders (or abandoned carts) containing this product, number of visits on the Product page, Conversion rate. By default, these functions return the 'Products purchased'. These functions also accept an optional parameter &abandonedCarts=1. If the parameter is set, it will instead return the metrics for products that were left in an abandoned cart therefore not purchased. The API also lets you request overall Goal metrics via the method "get": Conversions, Visits with at least one conversion, Conversion rate and Revenue. If you wish to request specific metrics about Ecommerce goals, you can set the parameter &idGoal=ecommerceAbandonedCart to get metrics about abandoned carts (including Lost revenue, and number of items left in the cart) or &idGoal=ecommerceOrder to get metrics about Ecommerce orders (number of orders, visits with an order, subtotal, tax, shipping, discount, revenue, items ordered) See also the documentation about Tracking Goals in Piwik.
- Goals.getGoals (idSite) [ Example in XML, Json, Tsv (Excel) ]
- Goals.addGoal (idSite, name, matchAttribute, pattern, patternType, caseSensitive = '', revenue = '', allowMultipleConversionsPerVisit = '') [ No example available ]
- Goals.updateGoal (idSite, idGoal, name, matchAttribute, pattern, patternType, caseSensitive = '', revenue = '', allowMultipleConversionsPerVisit = '') [ No example available ]
- Goals.deleteGoal (idSite, idGoal) [ No example available ]
- Goals.getItemsSku (idSite, period, date, abandonedCarts = '', segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Goals.getItemsName (idSite, period, date, abandonedCarts = '', segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Goals.getItemsCategory (idSite, period, date, abandonedCarts = '', segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Goals.get (idSite, period, date, segment = '', idGoal = '', columns = 'Array') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Goals.getDaysToConversion (idSite, period, date, segment = '', idGoal = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Goals.getVisitsUntilConversion (idSite, period, date, segment = '', idGoal = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module ImageGraph

The ImageGraph.get API call lets you generate beautiful static PNG Graphs for any existing Piwik report. Supported graph types are: line plot, 2D/3D pie chart and vertical bar chart. A few notes about some of the parameters available:
- $graphType defines the type of graph plotted, accepted values are: 'evolution', 'verticalBar', 'pie' and '3dPie'
- $colors accepts a comma delimited list of colors that will overwrite the default Piwik colors
- you can also customize the width, height, font size, metric being plotted (in case the data contains multiple columns/metrics). See also How to embed static Image Graphs? for more information.
- ImageGraph.get (idSite, period, date, apiModule, apiAction, graphType = '', outputType = '0', columns = '', labels = '', showLegend = '1', width = '', height = '', fontSize = '9', legendFontSize = '', aliasedGraph = '1', idGoal = '', colors = '', textColor = '222222', backgroundColor = 'FFFFFF', gridColor = 'CCCCCC', idSubtable = '', legendAppendMetric = '1', segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module LanguagesManager

The LanguagesManager API lets you access existing Piwik translations, and change Users languages preferences. "getTranslationsForLanguage" will return all translation strings for a given language, so you can leverage Piwik translations in your application (and automatically benefit from the 40+ translations!). This is mostly useful to developers who integrate Piwik API results in their own application. You can also request the default language to load for a user via "getLanguageForUser", or update it via "setLanguageForUser".
- LanguagesManager.isLanguageAvailable (languageCode) [ Example in XML, Json, Tsv (Excel) ]
- LanguagesManager.getAvailableLanguages () [ Example in XML, Json, Tsv (Excel) ]
- LanguagesManager.getAvailableLanguagesInfo () [ Example in XML, Json, Tsv (Excel) ]
- LanguagesManager.getAvailableLanguageNames () [ Example in XML, Json, Tsv (Excel) ]
- LanguagesManager.getTranslationsForLanguage (languageCode) [ Example in XML, Json, Tsv (Excel) ]
- LanguagesManager.getLanguageForUser (login) [ No example available ]
- LanguagesManager.setLanguageForUser (login, languageCode) [ No example available ]
↑ Back to top

Module Live

The Live! API lets you access complete visit level information about your visitors. Combined with the power of Segmentation, you will be able to request visits filtered by any criteria. The method "getLastVisitsDetails" will return extensive data for each visit, which includes: server time, visitId, visitorId, visitorType (new or returning), number of pages, list of all pages (and events, file downloaded and outlinks clicked), custom variables names and values set to this visit, number of goal conversions (and list of all Goal conversions for this visit, with time of conversion, revenue, URL, etc.), but also other attributes such as: days since last visit, days since first visit, country, continent, visitor IP, provider, referrer used (referrer name, keyword if it was a search engine, full URL), campaign name and keyword, operating system, browser, type of screen, resolution, supported browser plugins (flash, java, silverlight, pdf, etc.), various dates & times format to make it easier for API users... and more! With the parameter '&segment=' you can filter the returned visits by any criteria (visitor IP, visitor ID, country, keyword used, time of day, etc.). The method "getCounters" is used to return a simple counter: visits, number of actions, number of converted visits, in the last N minutes. See also the documentation about Real time widget and visitor level reports in Piwik.
- Live.getCounters (idSite, lastMinutes, segment = '') [ Example in XML, Json, Tsv (Excel) ]
- Live.getLastVisitsDetails (idSite, period = '', date = '', segment = '', countVisitorsToFetch = '', minTimestamp = '', flat = '', doNotFetchActions = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Live.getVisitorProfile (idSite, visitorId = '', segment = '', checkForLatLong = '') [ Example in XML, Json, Tsv (Excel) ]
- Live.getMostRecentVisitorId (idSite, segment = '') [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module MobileMessaging

The MobileMessaging API lets you manage and access all the MobileMessaging plugin features including : - manage SMS API credential - activate phone numbers - check remaining credits - send SMS
- MobileMessaging.areSMSAPICredentialProvided () [ Example in XML, Json, Tsv (Excel) ]
- MobileMessaging.getSMSProvider () [ Example in XML, Json, Tsv (Excel) ]
- MobileMessaging.setSMSAPICredential (provider, apiKey) [ No example available ]
- MobileMessaging.addPhoneNumber (phoneNumber) [ No example available ]
- MobileMessaging.getCreditLeft () [ Example in XML, Json, Tsv (Excel) ]
- MobileMessaging.removePhoneNumber (phoneNumber) [ No example available ]
- MobileMessaging.validatePhoneNumber (phoneNumber, verificationCode) [ No example available ]
- MobileMessaging.deleteSMSAPICredential () [ Example in XML, Json, Tsv (Excel) ]
- MobileMessaging.setDelegatedManagement (delegatedManagement) [ No example available ]
- MobileMessaging.getDelegatedManagement () [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module MultiSites

The MultiSites API lets you request the key metrics (visits, page views, revenue) for all Websites in Piwik.
- MultiSites.getAll (period, date, segment = '', enhanced = '', pattern = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- MultiSites.getOne (idSite, period, date, segment = '', enhanced = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module Overlay

Class API
- Overlay.getTranslations (idSite) [ Example in XML, Json, Tsv (Excel) ]
- Overlay.getExcludedQueryParameters (idSite) [ Example in XML, Json, Tsv (Excel) ]
- Overlay.getFollowingPages (url, idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module Provider

The Provider API lets you access reports for your visitors Internet Providers.
- Provider.getProvider (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module Referrers

The Referrers API lets you access reports about Websites, Search engines, Keywords, Campaigns used to access your website. For example, "getKeywords" returns all search engine keywords (with general analytics metrics for each keyword), "getWebsites" returns referrer websites (along with the full Referrer URL if the parameter &expanded=1 is set). "getReferrerType" returns the Referrer overview report. "getCampaigns" returns the list of all campaigns (and all campaign keywords if the parameter &expanded=1 is set). The methods "getKeywordsForPageUrl" and "getKeywordsForPageTitle" are used to output the top keywords used to find a page. Check out the widget "Top keywords used to find this page" that you can easily re-use on your website.
- Referrers.getReferrerType (idSite, period, date, segment = '', typeReferrer = '', idSubtable = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getAll (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getKeywords (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getKeywordsForPageUrl (idSite, period, date, url) [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getKeywordsForPageTitle (idSite, period, date, title) [ No example available ]
- Referrers.getSearchEnginesFromKeywordId (idSite, period, date, idSubtable, segment = '') [ No example available ]
- Referrers.getSearchEngines (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getKeywordsFromSearchEngineId (idSite, period, date, idSubtable, segment = '') [ No example available ]
- Referrers.getCampaigns (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getKeywordsFromCampaignId (idSite, period, date, idSubtable, segment = '') [ No example available ]
- Referrers.getWebsites (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getUrlsFromWebsiteId (idSite, period, date, idSubtable, segment = '') [ No example available ]
- Referrers.getSocials (idSite, period, date, segment = '', expanded = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getUrlsForSocial (idSite, period, date, segment = '', idSubtable = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getNumberOfDistinctSearchEngines (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getNumberOfDistinctKeywords (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getNumberOfDistinctCampaigns (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getNumberOfDistinctWebsites (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Referrers.getNumberOfDistinctWebsitesUrls (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module SEO

The SEO API lets you access a list of SEO metrics for the specified URL: Google Pagerank, Goolge/Bing indexed pages Alexa Rank, age of the Domain name and count of DMOZ entries.
- SEO.getRank (url) [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module ScheduledReports

The ScheduledReports API lets you manage Scheduled Email reports, as well as generate, download or email any existing report. "generateReport" will generate the requested report (for a specific date range, website and in the requested language). "sendEmailReport" will send the report by email to the recipients specified for this report. You can also get the list of all existing reports via "getReports", create new reports via "addReport", or manage existing reports with "updateReport" and "deleteReport". See also the documentation about Scheduled Email reports in Piwik.
- ScheduledReports.addReport (idSite, description, period, hour, reportType, reportFormat, reports, parameters, idSegment = '') [ No example available ]
- ScheduledReports.updateReport (idReport, idSite, description, period, hour, reportType, reportFormat, reports, parameters, idSegment = '') [ No example available ]
- ScheduledReports.deleteReport (idReport) [ No example available ]
- ScheduledReports.getReports (idSite = '', period = '', idReport = '', ifSuperUserReturnOnlySuperUserReports = '', idSegment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- ScheduledReports.generateReport (idReport, date, language = '', outputType = '', period = '', reportFormat = '', parameters = '') [ No example available ]
- ScheduledReports.sendReport (idReport, period = '', date = '') [ No example available ]
↑ Back to top

Module SegmentEditor

The SegmentEditor API lets you add, update, delete custom Segments, and list saved segments.a
- SegmentEditor.delete (idSegment) [ No example available ]
- SegmentEditor.update (idSegment, name, definition, idSite = '', autoArchive = '', enabledAllUsers = '') [ No example available ]
- SegmentEditor.add (name, definition, idSite = '', autoArchive = '', enabledAllUsers = '') [ No example available ]
- SegmentEditor.get (idSegment) [ No example available ]
- SegmentEditor.getAll (idSite = '', returnOnlyAutoArchived = '') [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module SitesManager

The SitesManager API gives you full control on Websites in Piwik (create, update and delete), and many methods to retrieve websites based on various attributes. This API lets you create websites via "addSite", update existing websites via "updateSite" and delete websites via "deleteSite". When creating websites, it can be useful to access internal codes used by Piwik for currencies via "getCurrencyList", or timezones via "getTimezonesList". There are also many ways to request a list of websites: from the website ID via "getSiteFromId" or the site URL via "getSitesIdFromSiteUrl". Often, the most useful technique is to list all websites that are known to a current user, based on the token_auth, via "getSitesWithAdminAccess", "getSitesWithViewAccess" or "getSitesWithAtLeastViewAccess" (which returns both). Some methods will affect all websites globally: "setGlobalExcludedIps" will set the list of IPs to be excluded on all websites, "setGlobalExcludedQueryParameters" will set the list of URL parameters to remove from URLs for all websites. The existing values can be fetched via "getExcludedIpsGlobal" and "getExcludedQueryParametersGlobal". See also the documentation about Managing Websites in Piwik.
- SitesManager.getJavascriptTag (idSite, piwikUrl = '', mergeSubdomains = '', groupPageTitlesByDomain = '', mergeAliasUrls = '', visitorCustomVariables = '', pageCustomVariables = '', customCampaignNameQueryParam = '', customCampaignKeywordParam = '', doNotTrack = '') [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesFromGroup (group) [ No example available ]
- SitesManager.getSitesGroups () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSiteFromId (idSite) [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSiteUrlsFromId (idSite) [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getAllSites () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getAllSitesId () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesIdWithVisits (timestamp = '') [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesWithAdminAccess () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesWithViewAccess () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesWithAtLeastViewAccess (limit = '') [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesIdWithAdminAccess () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesIdWithViewAccess () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesIdWithAtLeastViewAccess () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSitesIdFromSiteUrl (url) [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.addSite (siteName, urls, ecommerce = '', siteSearch = '', searchKeywordParameters = '', searchCategoryParameters = '', excludedIps = '', excludedQueryParameters = '', timezone = '', currency = '', group = '', startDate = '', excludedUserAgents = '', keepURLFragments = '', type = '') [ No example available ]
- SitesManager.deleteSite (idSite) [ No example available ]
- SitesManager.addSiteAliasUrls (idSite, urls) [ No example available ]
- SitesManager.getIpsForRange (ipRange) [ No example available ]
- SitesManager.setGlobalExcludedIps (excludedIps) [ No example available ]
- SitesManager.setGlobalSearchParameters (searchKeywordParameters, searchCategoryParameters) [ No example available ]
- SitesManager.getSearchKeywordParametersGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getSearchCategoryParametersGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getExcludedQueryParametersGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getExcludedUserAgentsGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.setGlobalExcludedUserAgents (excludedUserAgents) [ No example available ]
- SitesManager.isSiteSpecificUserAgentExcludeEnabled () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.setSiteSpecificUserAgentExcludeEnabled (enabled) [ No example available ]
- SitesManager.getKeepURLFragmentsGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.setKeepURLFragmentsGlobal (enabled) [ No example available ]
- SitesManager.setGlobalExcludedQueryParameters (excludedQueryParameters) [ No example available ]
- SitesManager.getExcludedIpsGlobal () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getDefaultCurrency () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.setDefaultCurrency (defaultCurrency) [ No example available ]
- SitesManager.getDefaultTimezone () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.setDefaultTimezone (defaultTimezone) [ No example available ]
- SitesManager.updateSite (idSite, siteName, urls = '', ecommerce = '', siteSearch = '', searchKeywordParameters = '', searchCategoryParameters = '', excludedIps = '', excludedQueryParameters = '', timezone = '', currency = '', group = '', startDate = '', excludedUserAgents = '', keepURLFragments = '', type = '') [ No example available ]
- SitesManager.getCurrencyList () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getCurrencySymbols () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getTimezonesList () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getUniqueSiteTimezones () [ Example in XML, Json, Tsv (Excel) ]
- SitesManager.getPatternMatchSites (pattern) [ No example available ]
↑ Back to top

Module Transitions

- Transitions.getTransitionsForPageTitle (pageTitle, idSite, period, date, segment = '', limitBeforeGrouping = '') [ No example available ]
- Transitions.getTransitionsForPageUrl (pageUrl, idSite, period, date, segment = '', limitBeforeGrouping = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- Transitions.getTransitionsForAction (actionName, actionType, idSite, period, date, segment = '', limitBeforeGrouping = '', parts = 'all') [ No example available ]
- Transitions.getTranslations () [ Example in XML, Json, Tsv (Excel) ]
↑ Back to top

Module UserCountry

The UserCountry API lets you access reports about your visitors' Countries and Continents.
- UserCountry.getCountry (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserCountry.getContinent (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserCountry.getRegion (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserCountry.getCity (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserCountry.getLocationFromIP (ip, provider = '') [ Example in XML, Json, Tsv (Excel) ]
- UserCountry.getNumberOfDistinctCountries (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module UserSettings

The UserSettings API lets you access reports about your Visitors technical settings: browsers, browser types (rendering engine), operating systems, plugins supported in their browser, Screen resolution and Screen types (normal, widescreen, dual screen or mobile).
- UserSettings.getResolution (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getConfiguration (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getOS (idSite, period, date, segment = '', addShortLabel = '1') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getOSFamily (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getMobileVsDesktop (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getBrowserVersion (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getBrowser (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getBrowserType (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getWideScreen (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getPlugin (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- UserSettings.getLanguage (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module UsersManager

The UsersManager API lets you Manage Users and their permissions to access specific websites. You can create users via "addUser", update existing users via "updateUser" and delete users via "deleteUser". There are many ways to list users based on their login "getUser" and "getUsers", their email "getUserByEmail", or which users have permission (view or admin) to access the specified websites "getUsersWithSiteAccess". Existing Permissions are listed given a login via "getSitesAccessFromUser", or a website ID via "getUsersAccessFromSite", or you can list all users and websites for a given permission via "getUsersSitesFromAccess". Permissions are set and updated via the method "setUserAccess". See also the documentation about Managing Users in Piwik.
- UsersManager.setUserPreference (userLogin, preferenceName, preferenceValue) [ No example available ]
- UsersManager.getUserPreference (userLogin, preferenceName) [ No example available ]
- UsersManager.getUsers (userLogins = '') [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getUsersLogin () [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getUsersSitesFromAccess (access) [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getUsersAccessFromSite (idSite) [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getUsersWithSiteAccess (idSite, access) [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getSitesAccessFromUser (userLogin) [ Example in XML, Json, Tsv (Excel) ]
- UsersManager.getUser (userLogin) [ Example in XML, Json, Tsv (Excel) ]
- 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, Json, Tsv (Excel) ]
- UsersManager.userEmailExists (userEmail) [ No example available ]
- UsersManager.setUserAccess (userLogin, access, idSites) [ No example available ]
- UsersManager.getTokenAuth (userLogin, md5Password) [ No example available ]
↑ Back to top

Module VisitFrequency

VisitFrequency API lets you access a list of metrics related to Returning Visitors.
- VisitFrequency.get (idSite, period, date, segment = '', columns = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module VisitTime

VisitTime API lets you access reports by Hour (Server time), and by Hour Local Time of your visitors.
- VisitTime.getVisitInformationPerLocalTime (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitTime.getVisitInformationPerServerTime (idSite, period, date, segment = '', hideFutureHoursWhenToday = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitTime.getByDayOfWeek (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module VisitorInterest

VisitorInterest API lets you access two Visitor Engagement reports: number of visits per number of pages, and number of visits per visit duration.
- VisitorInterest.getNumberOfVisitsPerVisitDuration (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitorInterest.getNumberOfVisitsPerPage (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitorInterest.getNumberOfVisitsByDaysSinceLast (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitorInterest.getNumberOfVisitsByVisitCount (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top

Module VisitsSummary

VisitsSummary API lets you access the core web analytics metrics (visits, unique visitors, count of actions (page views & downloads & clicks on outlinks), time on site, bounces and converted visits.
- VisitsSummary.get (idSite, period, date, segment = '', columns = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getVisits (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getUniqueVisitors (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getActions (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getMaxActions (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getBounceCount (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getVisitsConverted (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getSumVisitsLength (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
- VisitsSummary.getSumVisitsLengthPretty (idSite, period, date, segment = '') [ Example in XML, Json, Tsv (Excel) , RSS of the last 10 days ]
↑ Back to top