PHP Class Piwik\Plugins\API\API

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
Inheritance: extends Piwik\Plugin\API
Show file Open project: piwik/piwik Class Usage Examples

Public Methods

Method Description
__construct ( SettingsProvider $settingsProvider, ProcessedReport $processedReport )
get ( $idSite, $period, $date, $segment = false, $columns = false ) Get a combined report of the *.get API methods.
getAvailableMeasurableTypes ( ) : array Returns all available measurable types.
getBulkRequest ( array $urls ) : array Performs multiple API requests at once and returns every result.
getDefaultMetricTranslations ( ) : array Default translations for many core metrics.
getGlossaryMetrics ( $idSite ) : array A glossary of all metrics and their definition
getGlossaryReports ( $idSite ) : array A glossary of all reports and their definition
getHeaderLogoUrl ( boolean $pathOnly = false ) : string Returns the url to header logo (~127x50px)
getIpFromHeader ( ) : string Returns the most accurate IP address available for the current user, in IPv4 format. This could be the proxy client's IP address.
getLogoUrl ( boolean $pathOnly = false ) : string Returns the url to application logo (~280x110px)
getMetadata ( $idSite, $apiModule, $apiAction, $apiParameters = [], $language = false, $period = false, $date = false, $hideMetricsDoc = false, $showSubtableReports = false ) Loads reports metadata, then return the requested one, matching optional API parameters.
getPiwikVersion ( ) : string Get Piwik version
getProcessedReport ( $idSite, $period, $date, $apiModule, $apiAction, $segment = false, $apiParameters = false, $idGoal = false, $language = false, $showTimer = true, $hideMetricsDoc = false, $idSubtable = false, $showRawMetrics = false, $format_metrics = null, $idDimension = false )
getReportMetadata ( string $idSites = '', boolean | string $period = false, boolean | Date $date = false, boolean $hideMetricsDoc = false, boolean $showSubtableReports = false, integer $idSite = false ) : array Triggers a hook to ask plugins for available Reports.
getReportPagesMetadata ( integer $idSite ) : array Get a list of all pages that shall be shown in a Piwik UI including a list of all widgets that shall be shown within each page.
getRowEvolution ( integer $idSite, string $period, Date $date, string $apiModule, string $apiAction, boolean | string $label = false, boolean | string $segment = false, boolean | string $column = false, boolean | string $language = false, boolean | integer $idGoal = false, boolean | string $legendAppendMetric = true, boolean | string $labelUseAbsoluteUrl = true, boolean | integer $idDimension = false ) : array Given an API report to query (eg. "Referrers.getKeywords", and a Label (eg. "free%20software"), this function will query the API for the previous days/weeks/etc. and will return a ready to use data structure containing the metrics for the requested Label, along with enriched information (min/max values, etc.)
getSVGLogoUrl ( boolean $pathOnly = false ) : string Returns the URL to application SVG Logo
getSegmentsMetadata ( $idSites = [], $_hideImplementationData = true )
getSettings ( ) : array Returns the section [APISettings] if defined in config.ini.php
getSuggestedValuesForSegment ( $segmentName, $idSite ) : array Given a segment, will return a list of the most used values for this particular segment.
getWidgetMetadata ( integer $idSite ) : array Get a list of all widgetizable widgets.
hasSVGLogo ( ) : boolean Returns whether there is an SVG Logo available.
isPluginActivated ( string $pluginName ) : boolean Return true if plugin is activated, false otherwise

Protected Methods

Method Description
doesSegmentNeedActionsData ( $segmentName ) : boolean
getSegmentValuesFromVisitorLog ( $segmentName, $table ) : array

Private Methods

Method Description
doesSuggestedValuesCallbackNeedData ( $suggestedValuesCallback )
findSegment ( $segmentName, $idSite )
getMostFrequentValues ( $values ) : array
getSuggestedValuesForSegmentName ( $idSite, $segment, $maxSuggestionsToReturn )

Method Details

__construct() public method

public __construct ( SettingsProvider $settingsProvider, ProcessedReport $processedReport )
$settingsProvider Piwik\Plugin\SettingsProvider
$processedReport ProcessedReport

doesSegmentNeedActionsData() protected method

protected doesSegmentNeedActionsData ( $segmentName ) : boolean
$segmentName
return boolean

get() public method

Get a combined report of the *.get API methods.
public get ( $idSite, $period, $date, $segment = false, $columns = false )

getAvailableMeasurableTypes() public method

Marked as deprecated so it won't appear in API page. It won't be a public API for now.
Deprecation:
public getAvailableMeasurableTypes ( ) : array
return array

getBulkRequest() public method

Performs multiple API requests at once and returns every result.
public getBulkRequest ( array $urls ) : array
$urls array The array of API requests.
return array

getDefaultMetricTranslations() public method

This is used for exports with translated labels. The exports contain columns that are not visible in the UI and not present in the API meta data. These columns are translated here.
Deprecation: since Piwik 2.15.1
public getDefaultMetricTranslations ( ) : array
return array

getGlossaryMetrics() public method

A glossary of all metrics and their definition
public getGlossaryMetrics ( $idSite ) : array
$idSite
return array

getGlossaryReports() public method

A glossary of all reports and their definition
public getGlossaryReports ( $idSite ) : array
$idSite
return array

getHeaderLogoUrl() public method

Returns the url to header logo (~127x50px)
Deprecation: since Piwik 2.15.1
public getHeaderLogoUrl ( boolean $pathOnly = false ) : string
$pathOnly boolean If true, returns path relative to doc root. Otherwise, returns a URL.
return string

getIpFromHeader() public method

Returns the most accurate IP address available for the current user, in IPv4 format. This could be the proxy client's IP address.
public getIpFromHeader ( ) : string
return string IP address in presentation format.

getLogoUrl() public method

Returns the url to application logo (~280x110px)
Deprecation: since Piwik 2.15.1
public getLogoUrl ( boolean $pathOnly = false ) : string
$pathOnly boolean If true, returns path relative to doc root. Otherwise, returns a URL.
return string

getMetadata() public method

Loads reports metadata, then return the requested one, matching optional API parameters.
public getMetadata ( $idSite, $apiModule, $apiAction, $apiParameters = [], $language = false, $period = false, $date = false, $hideMetricsDoc = false, $showSubtableReports = false )

getPiwikVersion() public method

Get Piwik version
public getPiwikVersion ( ) : string
return string

getProcessedReport() public method

public getProcessedReport ( $idSite, $period, $date, $apiModule, $apiAction, $segment = false, $apiParameters = false, $idGoal = false, $language = false, $showTimer = true, $hideMetricsDoc = false, $idSubtable = false, $showRawMetrics = false, $format_metrics = null, $idDimension = false )

getReportMetadata() public method

Returns metadata information about each report (category, name, dimension, metrics, etc.)
public getReportMetadata ( string $idSites = '', boolean | string $period = false, boolean | Date $date = false, boolean $hideMetricsDoc = false, boolean $showSubtableReports = false, integer $idSite = false ) : array
$idSites string THIS PARAMETER IS DEPRECATED AND WILL BE REMOVED IN PIWIK 4
$period boolean | string
$date boolean | Piwik\Date
$hideMetricsDoc boolean
$showSubtableReports boolean
$idSite integer
return array

getReportPagesMetadata() public method

Get a list of all pages that shall be shown in a Piwik UI including a list of all widgets that shall be shown within each page.
public getReportPagesMetadata ( integer $idSite ) : array
$idSite integer
return array

getRowEvolution() public method

Given an API report to query (eg. "Referrers.getKeywords", and a Label (eg. "free%20software"), this function will query the API for the previous days/weeks/etc. and will return a ready to use data structure containing the metrics for the requested Label, along with enriched information (min/max values, etc.)
public getRowEvolution ( integer $idSite, string $period, Date $date, string $apiModule, string $apiAction, boolean | string $label = false, boolean | string $segment = false, boolean | string $column = false, boolean | string $language = false, boolean | integer $idGoal = false, boolean | string $legendAppendMetric = true, boolean | string $labelUseAbsoluteUrl = true, boolean | integer $idDimension = false ) : array
$idSite integer
$period string
$date Piwik\Date
$apiModule string
$apiAction string
$label boolean | string
$segment boolean | string
$column boolean | string
$language boolean | string
$idGoal boolean | integer
$legendAppendMetric boolean | string
$labelUseAbsoluteUrl boolean | string
$idDimension boolean | integer
return array

getSVGLogoUrl() public method

Returns the URL to application SVG Logo
public getSVGLogoUrl ( boolean $pathOnly = false ) : string
$pathOnly boolean If true, returns path relative to doc root. Otherwise, returns a URL.
return string

getSegmentValuesFromVisitorLog() protected method

protected getSegmentValuesFromVisitorLog ( $segmentName, $table ) : array
$segmentName
$table
return array

getSegmentsMetadata() public method

public getSegmentsMetadata ( $idSites = [], $_hideImplementationData = true )

getSettings() public method

Returns the section [APISettings] if defined in config.ini.php
public getSettings ( ) : array
return array

getSuggestedValuesForSegment() public method

Given a segment, will return a list of the most used values for this particular segment.
public getSuggestedValuesForSegment ( $segmentName, $idSite ) : array
$segmentName
$idSite
return array

getWidgetMetadata() public method

Get a list of all widgetizable widgets.
public getWidgetMetadata ( integer $idSite ) : array
$idSite integer
return array

isPluginActivated() public method

Return true if plugin is activated, false otherwise
public isPluginActivated ( string $pluginName ) : boolean
$pluginName string
return boolean