Adobe Marketing Cloud Reporting API 1.4
November 17, 2017 | Author: Philippa Page | Category: N/A
Short Description
Download Adobe Marketing Cloud Reporting API 1.4...
Description
Adobe® Marketing Cloud
Reporting API 1.4
Contents Getting Started.................................................................................................................5 What's New......................................................................................................................10 Authentication................................................................................................................14 Methods...........................................................................................................................15 Cancel..................................................................................................................................................................................15 Get.........................................................................................................................................................................................15 GetElements......................................................................................................................................................................15 GetMetrics..........................................................................................................................................................................16 GetQueue...........................................................................................................................................................................17 Run........................................................................................................................................................................................17 Queue..................................................................................................................................................................................18 Validate...............................................................................................................................................................................19
Data Types.......................................................................................................................21 report...................................................................................................................................................................................21 reportData..........................................................................................................................................................................21 reportDataPath................................................................................................................................................................23 reportDataPathList.........................................................................................................................................................23 reportDescription............................................................................................................................................................23 reportDescriptionDateGranularity............................................................................................................................26 reportDescriptionElement...........................................................................................................................................27 reportDescriptionElementDataEncoding...............................................................................................................27 reportDescriptionElementList....................................................................................................................................28 reportDescriptionLocale...............................................................................................................................................28 reportDescriptionMetric...............................................................................................................................................28 reportDescriptionMetricList........................................................................................................................................28
Last updated 11/6/2014
Reporting API 1.4
Contents
reportDescriptionSearch..............................................................................................................................................29 reportDescriptionSearchType....................................................................................................................................29 reportDescriptionSegment..........................................................................................................................................29 reportDescriptionSegmentList...................................................................................................................................30 reportDescriptionSource..............................................................................................................................................30 reportElement..................................................................................................................................................................31 reportElementInfo...........................................................................................................................................................31 reportElementList...........................................................................................................................................................31 reportMetric......................................................................................................................................................................31 reportMetricInfo..............................................................................................................................................................32 reportMetricList...............................................................................................................................................................32 reportReportSuite...........................................................................................................................................................32 reportResponse................................................................................................................................................................33 reportSegment.................................................................................................................................................................33 report_queue_item........................................................................................................................................................33 report_queue_item_array............................................................................................................................................34
Analytics Elements.........................................................................................................35 Analytics Metrics.............................................................................................................40 Valid Element and Metric Combinations......................................................................46 Analytics Report Error Codes.........................................................................................48 Anomaly Detection.........................................................................................................51 Inline Segmentation.......................................................................................................52 Real-Time Reports..........................................................................................................55 Summary Reports...........................................................................................................59
Last updated 11/6/2014
Reporting API 1.4
Pathing Reports..............................................................................................................61
Last updated 11/6/2014
Reporting API 1.4
Getting Started
Getting Started To get started, review the changes in 1.4, update your endpoint, and then use the examples to start generating reports. Report Queue Workflow
1. Open the API Explorer in Developer Connection. 2. Send a request using Report API and the method Report.Queue. The Report API will return a report ID. 3. Change the method to Report.Get using the report ID. There will be one of 2 responses: • A "report not ready" response: { "error":"report_not_ready", "error_description":"Report not ready", "error_uri":null }
• Or a return of the whole report. Here are some best practices: • Check for a report every few seconds. Do not check more than once a second. • You can queue up multiple reports to be run concurrently. • The response from Report.Queue is exactly the same as the request for Report.Get. Endpoint API requests should be sent to the 1.4 endpoint: https://api.omniture.com/admin/1.4/
5
Getting Started
6
You might need to replace api.omniture.com with the URL that corresponds to your data center, as listed in the following table. In your production apps, we recommend calling Company.GetEndpoint to periodically refresh the endpoint programmatically, in case the URL changes. • api.omniture.com - San Jose • api2.omniture.com - Dallas • api3.omniture.com - London • api4.omniture.com - Singapore • api5.omniture.com - Pacific Northwest Removal of separate methods to generate different report types If you are migrating from a previous version of the API, report types are now determined by the parameters of the reportDescription according to the following table: Report Type
Parameters
Overtime Report
No elements with a dateGranularity specified.
Ranked Report
1 or more elements with no dateGranularity specified.
Trended Report
1 or more elements with a dateGranularity specified.
Pathing Report
Element in the pattern parameter.
Fallout Report
Element in the checkpoint parameter.
Summary Report
No "reportSuiteID" parameter, instead "reportsuite" is specified as the report element and the "selected" parameter contains a list of report suite IDs.
Real-Time Report
'source' parameter present and set to 'realtime'. Note that Real-Time Reports do not have to be queued, they can run immediately using Report.Run.
The type derived is then returned in the result data as: ranked, trended, overtime, pathing, fallout, summary, or realtime. Using the API in the Browser The API supports CORS and can be used in most modern browsers in a cross-domain way. This library provides a way to do authentication with WSSE in Javascript. If you decide to use the browser, keep the following in mind: • If you have a lot of users using the application, you will need to cache the results on a server. Do not publish a script on your public web site that pulls directly from the API. • Some older browsers do not support CORS. Make sure your users are using a newer browser when trying to access the API. Adobe Analytics Real-Time Dashboard Example An example of how to create a real-time dashboard can be found on github. Examples In the following examples, replace "rsid" with your report suite id, and update the URL to use the correct endpoint. //Simplest Request https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid" } } //overtime report
Getting Started
https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "dateGranularity":"hour" } } //Ranked Report https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "elements":[ {"id":"page"} ] } } //Trended Report https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "dateGranularity":"hour", "elements":[ {"id":"page"} ] } } //Pathing Report -- NextPage Flow https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "top":"10", "startingWith":"1", "pattern":[ ["homepage"], ["::anything::"], ["::anything::"], ["::anything::"], ["::anything::"] ]} ] } } //Pathing Report -- PreviousPage Flow https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "pattern":[ ["::anything::"], ["::anything::"], ["::anything::"], ["::anything::"],
7
Getting Started
8
["homepage"], ]} ] } } //Pathing Report -- Fallout https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "checkpoints":[ "homepage", "/templates/choose-your-powerpoint-fonts-wisely/" ]} ] } } // Real-Time Report // Note the inclusion of "source" equals "realtime" // Make sure you configure Real-Time reports for the report suite https://api.omniture.com/admin/1.4/rest/?method=Report.Run { "reportDescription": { "source": "realtime", "reportSuiteID": "rsid", "metrics": [ { "id": "revenue" } ] } } // Real-Time Report with sort options https://api.omniture.com/admin/1.4/rest/?method=Report.Run { "reportDescription": { "source": "realtime", "reportSuiteID": "rsid", "sortMethod": "mostPopular:.25:0:linear", "metrics": [ { "id": "pageviews" } ] } } // Summary Report // Note that the "reportSuiteID" parameter is not included // and the elements list contains "reportsuite" // Report suites are provided in the "selected" element https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "date":"2014", "metrics":[ { "id":"pageviews", }, { "id":"revenue", }, ], "elements":[ {
Getting Started
9
"id":"reportsuite", "selected":[ "rsid1", "rsid2" ] } ], } } //Error Message https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "dateGranularity":"hours" } } //Validate Report Definiton (without Queuing it) https://api.omniture.com/admin/1.4/rest/?method=Report.Validate { "reportDescription":{ "reportSuiteID":"rsid", "dateGranularity":"hours" } } //GetMetrics https://api.omniture.com/admin/1.4/rest/?method=Report.GetMetrics { "reportSuiteID":"rsid", "existingElements":["page"] } //GetElements https://api.omniture.com/admin/1.4/rest/?method=Report.GetMetrics { "reportSuiteID":"rsid", "existingMetrics":["pageviews"] }
What's New
10
What's New Note: Version 1.2 of the web services API is officially deprecated and is scheduled for end-of-life early 2015. Version 1.3 continues to be supported, though customers are encouraged to migrate to the 1.4 API to leverage the improvements described on this page. May 22, 2014 The following report types are now available: • Real-Time Reports • Summary Reports An elementDataEncoding parameter was added to reportDescription to help resolve report data encoding issues. Segmentation Changes With the release of Adobe Analytics unified segmentation, the following changes apply to segments in the 1.4 Admin and Reporting APIs: Report.Queue • Accepts existing segments and new segments created in the new Segment Builder UI. • Allows applying legacy Pre-Configured and Suite segments without validation. ReportSuite.GetSegments and ReportSuite.GetSettings • Returns only segments that appear in the new Segment Builder UI. Most segments are migrated to the Segment Builder automatically, with the exception of some pre-defined segments. • All segments available for the authenticated user are returned. • Pre-Configured and Suite segments are no longer returned. These segments are now templates, so you'll need to create a custom segment based on a template to use these segments. Changes in Version 1.4 OAuth authentication Version 1.4 of the reporting API supports OAuth2 authentication, and maintains support for the version 1.3 password digest authentication mechanism. Pathing reports You can now run pathing and fallout reports in the reporting API. Removal of separate methods to generate different report types Report types are now determined by the parameters of the reportDescription according to the following table: Overtime Report
No elements with a dateGranularity specified.
Ranked Report
1 or more elements with no dateGranularity specified.
Trended Report
1 or more elements with a dateGranularity specified.
Pathing Report
Element in the pattern parameter.
Fallout Report
Element in the checkpoint parameter.
What's New
The type derived is then returned in the result data as: ranked, trended, overtime, pathing, or fallout. Calculated metrics now included in Report.GetMetrics GetMetrics now returns configured calculated metrics for the report suite along with the other reporting API metrics. The IDs of these metrics are in the form "f:" where is some integer value. The metric type, decimal precision, and formula (where applicable) are included for all metrics. Conversion of formulas and validation against metric and element settings are now handled by the Reporting API. Full Hierarchy reports support hier# elements are now fully supported in both ranked and trended reports. New metrics • returnvisits • returnvisitsdaily Removed: • cpageviews • cvisits • cvisitor New elements • pagefallout • pagepaths • sitesectionfallout • sitesectionpaths • prop#path (Note: For Custom Traffic Vars with Pathing enabled) • prop#fallout (Note: For Custom Traffic Vars with Pathing enabled) Removed: • cpage • listvar4 • listvar5 Default report description parameters metrics If the list of metrics is left empty, the default metric of "pageviews" is used. date/dateFrom/dateTo If the date parameter(s) are omitted, the current day is used. Improved error reporting In addition to fixing several issues that previously resulted in silent errors or zeros and null values in data, over 50 new error messages were added. The following sections describe some of the restrictions that are enforced to prevent errors. Element breakdown enforcement
11
What's New
12
Elements now have restrictions on which other elements they can be combined with in a report. Use GetElements with the existingElements parameter to get a list of valid breakdowns for a specific element. There are three groups of elements: Traffic, Commerce, and Both. Elements from the Traffic and Commerce groups may only be broken down by elements in the same group. Elements in the "Both" group can be broken down by any other element. A report may have a maximum number of three elements. See Analytics Elements. Element/Metric combination enforcement Certain metrics may only be requested along with certain elements. Use GetMetrics with the existingElements parameter to programmatically get a list of valid metrics for a list of element(s). Every element has either a metric whitelist or a metric blacklist, whichever is shorter, that determines these restrictions. See Valid Element and Metric Combinations. Overtime-only metrics enforcement Some metrics are only valid in overtime reports. Use GetMetrics with the dateGranularity parameter to programmatically get a list of these metrics. See Analytics Metrics. Inline segment elements enforcement The following elements are not supported for inline segments. • pagedepth • visitnumber • mobilecarrier • hier* • *paths • *fallout Maximum number of "top" elements enforcement The maximum number of top elements that can be requested is 50,000. Setting the "top" parameter to a number greater than 50000 will result in a element_top_invalid error. Date Enforcement Minimum date enforcement Due to specific system requirements, the minimum date that can be used in the date, dateFrom, and dateTo parameters is 2000-01-01. Requesting a date earlier than 2000-01-01 will result in a period_invalid error. Maximum date enforcement Due to specific system requirements, the maximum date that can be used in the date, dateFrom, and dateTo parameters is 2899-12-31. Requesting a date later than 2899-12-31 will result in a period_invalid error. Valid date range enforcement Requesting a toDate that is earlier than fromDate will result in a period_invalid error.
What's New
13
Report permissions enforcement Specific users may not have access to certain metrics or elements. The metrics and elements returned in GetMetrics and GetElements, respectively, reflect those restrictions. Requesting an element or metric that one doesn't have permission to access will result in a element_inaccessible or metric_inaccessible error. Validation of report immediately when calling Report.Queue The reportDescription is now validated right away when queuing, as well as at execution time. More descriptive error messages Numeric error codes have been abandoned in favor of textual, descriptive error messages. See Analytics Report Error Codes.
Authentication
14
Authentication Version 1.4 of the reporting API supports OAuth2 authentication, and maintains support for the version 1.3 password digest authentication mechanism. See Authentication.
Methods
15
Methods Cancel Cancels a previously submitted report request, and removes it from the processing queue. Method parameters are required unless noted otherwise. Report.Cancel parameters Name
Type
Description
reportID
xsd:int
Report ID returned by Report.Queue.
Report.Cancel response Type
Description
xsd:boolean
Returns true if the operation is successful.
Get Retrieves a report queued using Report.Queue Report.Get Parameters Name
Type
reportID
xsd:int
Description Report ID returned by Report.Queue.
Report.Get response Type reportResponse
Description Contains the requested report data. If the report is not ready, a HTTP 400 error is returned. {"error":"report_not_ready","error_description":"Report not ready","error_uri":null}
GetElements Retrieves a list of possible valid elements for a report. See Analytics Elements.
Methods
16
Permissions Specific users may not have access to certain elements. The metrics returned by GetElements reflect those restrictions. Requesting an element that one doesn't have permission to access will result in a element_inaccessible error. Report.GetElements Parameters Name
Type
Description
reportSuiteID
xsd:string
The Analytics report suite you want to use to generate the report. For example: reportSuiteID = "corp1"
existingElements
array(xsd:string)
(optional) Include a list of elements already present in the reportDescription to get compatible metrics.
existingMetrics
array(xsd:string)
(optional) Include a list of metrics already present in the reportDescription to get compatible metrics.
reportType
xsd:string
(optional) Include the report type (any, ranked, trended, pathing, fallout, realtime) to get compatible metrics.
Report.GetElements response Type
Description
reportElementList - An
Defines an element that appears in a report.
array of reportElement
GetMetrics Retrieves a list of possible valid elements for a report. See Analytics Metrics. Permissions Specific users may not have access to certain metrics. The metrics returned by GetMetrics reflect those restrictions. Requesting a metric that one doesn't have permission to access results in a metric_inaccessible error. Report.GetMetrics Parameters Name
Type
Description
reportSuiteID
xsd:string
The Analytics report suite you want to use to generate the report. For example: reportSuiteID = "corp1"
existingElements
array(xsd:string)
(optional) Include a list of elements already present in the reportDescription to get compatible metrics.
Methods
17
Name
Type
Description
existingMetrics
array(xsd:string)
(optional) Include a list of metrics already present in the reportDescription to get compatible metrics.
reportType
xsd:string
(optional) Include the report type (any, ranked, trended, pathing, fallout, realtime) to get compatible metrics.
Report.GetMetrics response Type
Description
reportMetricList - An
A structure that defines a metric that appears in a report.
array of reportMetric
GetQueue Returns a list of reports in a company's report queue. Report.GetQueue parameters None. Report.GetQueue response Type
Description
report_queue_item_array- A list of the company's currently queued report requests. The company is determined by the
An array of
authentication credentials provided with the request.
report_queue_item
Run Run a real-time report immediately without using the queue. Report.Run Parameters Name
Type
reportDescription
reportDescription
Description A report description that specifies the desired report contents. This data structure is validated automatically before the report is generated.
Methods
18
Report.Run response Type
Description
reportResponse
Contains the requested report data.
Report Type Report types are determined by the parameters of the reportDescription according to the following table: Report Type
Parameters
Overtime Report
No elements with a dateGranularity specified. Not supported by Run, use Report.Queue instead.
Ranked Report
1 or more elements with no dateGranularity specified. Not supported by Run, use Report.Queue instead.
Trended Report
1 or more elements with a dateGranularity specified. Not supported by Run, use Report.Queue instead.
Pathing Report
Element in the pattern parameter. Not supported by Run, use Report.Queue instead.
Fallout Report
Element in the checkpoint parameter. Not supported by Run, use Report.Queue instead.
Summary Report
No "reportSuiteID" parameter, instead "reportsuite" is specified as the report element and the "selected" parameter contains a list of report suite IDs. Not supported by Run, use Report.Queue instead.
Real-Time Report
"source" parameter present and set to "realtime".
The type derived is then returned in the result data as: ranked, trended, overtime, pathing, fallout, summary, or realtime. metrics If the list of metrics is left empty, the default metric of "pageviews" is used. elements If the list of elements is left empty, the default element of "page" is used. date/dateFrom/dateTo If the date parameter(s) are omitted, the current day is used.
Queue Queue a report to run. Report.Queue Parameters Name
Type
reportDescription
reportDescription
Description A report description that specifies the desired report contents. This data structure is validated automatically before the report is generated.
Methods
19
Report.Queue Response Name
Type
reportID
xsd:int
Description The ID of the report. Pass this ID to Report.Get to retrieve the report.
Report Type Report types are determined by the parameters of the reportDescription according to the following table: Report Type
Parameters
Overtime Report
No elements with a dateGranularity specified.
Ranked Report
1 or more elements with no dateGranularity specified.
Trended Report
1 or more elements with a dateGranularity specified.
Pathing Report
Element in the pattern parameter.
Fallout Report
Element in the checkpoint parameter.
Summary Report
No "reportSuiteID" parameter, instead "reportsuite" is specified as the report element and the "selected" parameter contains a list of report suite IDs.
Real-Time Report
'source' parameter present and set to 'realtime'. Note that Real-Time reports do not have to be queued, they can run immediately using Report.Run.
The type derived is then returned in the result data as: ranked, trended, overtime, pathing, fallout, summary, or realtime. metrics If the list of metrics is left empty, the default metric of "pageviews" is used. elements If the list of elements is left empty, the default element of "page" is used. date/dateFrom/dateTo If the date parameter(s) are omitted, the current day is used.
Validate Determines if a report description is valid without running the report. If the report is not valid, an error will be returned detailing the problem. Report.Validate Parameters Name
Type
reportDescription
reportDescription
Description The report structure that you want to validate.
Methods
20
Report.Validate Response Type
Description
xsd:boolean
Returns true if the operation is successful.
Data Types
21
Data Types report A structure data type that returns data associated with a particular report request. Element
Type
Description
type
xsd:string
reportSuite
reportReportSuite
period
xsd:string
elements
reportElementList - an array of A list of elements associated with the report. reportElement
metrics
reportMetricList - an array of reportMetric
segments
reportSegmentList - an array of List of segments to apply to the report. reportSegment
data
reportDataList - an array of reportData
totals
array(double)
version
xsd:string
The report type that was generated based on the provided parameters. See . String array that contains the report suite ID and name. A string describing the report time period.
A list of metrics associated with the report.
The data that makes up the bulk of the report. A list of metric totals.
reportData A structure that contains report data. Element
Type
name
xsd:string
url
xsd:string
path
reportDataPathList
- an array of reportDataPath
Description This data item name. The data item URL, if applicable to the selected element. For example, pages and links have a URL, but products do not. The path for pathing reports.
Data Types
22
Element
Type
parentID
xsd:string
year
xsd:int
month
xsd:int
day
xsd:int
hour
xsd:int
minute
xsd:int
trend
double
counts
double[]
upperBounds
double[]
lowerBounds
double[]
forecasts
double[]
breakdownTotal
double[]
breakdown
reportDataList - an array of reportData
(recursive)
Description Unique identifier for the element in a hierarchy report. Use in reportDescription to request the next level of the hierarch. The four-digit year for the item if the element is a date range for an Overtime or Trended report. The two-digit month for the item if the element is a date range for an Overtime or Trended report. The two-digit numeric day for the item if the element is a date range for an Overtime or Trended report. The two-digit numeric hour for the item if the element is a date range for an Overtime or Trended report. The two-digit numeric minute for the item if the element is a date range for a Real-Time report. The slope of the trend line so you can determine the relative change between report intervals. A count of the number of occurrences of each metric in the report. Upper level of the prediction interval. Values above this level are considered anomalous. Represents a 95% confidence that values will be below this level. Lower level of the prediction interval. Values below this level are considered anomalous. Represents a 95% confidence that values will be above this level. The predicted value based on the data analysis. This value is also the middle point between the upper and lower bounds. The total metrics values for the breakdown. This item's data, organized according to the next element. For example, a report of Browsers, broken down by page views, returns a report containing a listing of page views for each Browser type. This is only used in Ranked or Trended reports when multiple elements (Breakdowns) are specified. (recursive)
Data Types
23
reportDataPath A structure that identifies a data path that appears in a report. Element
Type
Description
name
xsd:string
The data path name.
url
xsd:string
The URL if the element is a page.
reportDataPathList An array of reportDataPath.
reportDescription A structure that contains information for creating a specific report. Parameters Element
Type
Description
reportSuiteID
xsd:string
The Analytics report suite you want to use to generate the report. For example: reportSuiteID = "corp1"
date
xsd:string
The date for which you want to run the report. When using date, do not use dateFrom and dateTo. The date format is YYYY-MM-DD (4 digit year, 2 digit month, and 2 digit day), but the month and day designators are optional. For example: date = "2009-01" Due to specific system requirements, the minimum date that can be used in the date, dateFrom, and dateTo parameters is 2000-01-01, and the maximum date is 2899-12-31. Requesting a date outside of this range results in a period_invalid error. If the date parameter(s) are not included, the current day is used. Real-Time Reports also support relative dates.
dateFrom
xsd:string
The starting date used to run the report for when using a data range. When using dateFrom, do not use date. The date format is YYYY-MM-DD (4 digit year, 2 digit month, and 2 digit day), but the month and day designators are optional. For example: date = "2009-01-15" Due to specific system requirements, the minimum date that can be used in the date, dateFrom, and dateTo parameters is 2000-01-01, and the maximum date is 2899-12-31. Requesting a date outside of this range results in a period_invalid error. Requesting a toDate that is earlier than fromDate will result in a period_invalid error. If the date parameter(s) are not included, the current day is used.
Data Types
Element
24
Type
Description Real-Time Reports also support relative dates.
dateTo
xsd:string
The ending date used to run the report for when using a data range. When using dateTo, do not use date. The date format is YYYY-MM-DD (4 digit year, 2 digit month, and 2 digit day), but the month and day designators are optional. For example: date = "2010-01-15" Due to specific system requirements, the minimum date that can be used in the date, dateFrom, and dateTo parameters is 2000-01-01, and the maximum date is 2899-12-31. Requesting a date outside of this range results in a period_invalid error. Requesting a toDate that is earlier than fromDate will result in a period_invalid error. If the date parameter(s) are not included, the current day is used. Real-Time Reports also support relative dates.
dateGranularity
reportDescriptionDateGranularity
The time units used to display data in a report that organizes the data by date, such as an Overtime report. For example: dateGranularity = "day". One of the following values: • minute (Real-Time reports only). Specify a minute interval as "minute:[interval]". The interval is an integer between 1-60 that specifies the interval to report. For example, 'minute:3' reports the request date range in 3-minute intervals. • hour • day • week • month • quarter • year
source
reportDescriptionSource
metrics
reportDescriptionMetricList
- An array of reportDescriptionMetric
Defaults to 'standard', specify 'realtime' to generate a Real-Time report. An array of the metrics to include in the report. A report must specify at least one metric (Ranked/Overtime reports support one or more metrics. Trended reports support only one metric.) For example:metrics = [ {id = "pageViews"},{id = "visits"} ]
If the list of metrics is left empty, the default metric of "pageviews" is used. elements
reportDescriptionElementList
- An array of reportDescriptionElement
A list of elements that breaks down (organizes) the metrics data in the report. For example, you can generate a report that breaks down page views (metric) by browser (element). For example: elements = [ {id = "trackingCode", classification = "campaigns", top = 2, startingWith = 10} ]
Data Types
Element
25
Type
Description A report may have a maximum number of three elements. Elements have restrictions on which other elements they can be combined with in a report. You can pass element to GetElements to get a list of valid breakdowns for a specific element.
locale
reportDescriptionLocale
sortMethod
xsd:string
The geographic locale where you want to run the report. Real-Time Report sort method. Used only when 'source' is set to 'realtime' s ee the sortMethod Options table below for details.
sortBy
xsd:string
segments
reportDescriptionSegmentList
- An array of reportDescriptionSegment
anomalyDetection xsd:boolean
The reportDescriptionMetric ID to sort by. This can be used when declaring multiple metrics for Ranked and Trended reports. By default, the first metric will be used to sort. Use this option to sort by any of the metrics requested. Defines one or more saved segments or an inline segment. See Inline Segmentation. Returns upper bounds, lower bounds, and forecast data for anomaly detection. See Anomaly Detection. Not supported by Ranked reports.
currentData
xsd:boolean
expedite
xsd:boolean
elementDataEncoding reportDescriptionElementDataEncoding
Include current data in the report. Generates the report with higher priority. To allow non-UTF-8 characters that are in element names to come through SOAP XML and JSON intact, this parameter filters out invalid characters, or encodes element names in Base64. If specified, this must be one of the following values: • utf8 • base64 Important If base64 encoding is used, the request must also have all element names base64 encoded. This includes names in "selected" and "search" filters, and the "pattern" and "checkpoint" pathing filters. This also applies to special keywords as well, such as "::entered::" and "::anything::". This also includes dates in the "name" field for overtime and trended reports. Element URLs are not encoded. If utf8 encoding is used, the API filters out invalid UTF-8 characters in the request and response. This allows the result to come back with some data, although the values may be missing information.
Data Types
26
sortMethod Options The following table describes the sort options provided for real-time reports using the sortMethod parameter. Options are provided in a delimited list as follows: :::
Option
Type
algorithm
xsd:string
Description (Optional) An array of values matching one of the following values: • 'mostpopular' • 'gainers' • 'losers' Default is 'mostpopular'.
floorSensitivity
xsd:int
firstRankPeriod
xsd:string
(Optional) A factor between 0 and 1 that is used to cut off low-count items from percentage ranking. Relative only to gainers/losers by percent. Default is .25. (Optional) Computes the ranking of elements by considering the element's counts from the firstRankPeriod to the final period. Default is 0. With this argument you can rank from the first period (0) to periodCount - 1 (most popular) or periodCount - 3 (gainers/losers) or anywhere in between. The firstRankPeriod is 0 based. Example: if periodCount is 15, you can pass in a firstRankPeriod of anywhere from 0-14 for most popular (the API considers only period 14), or 0-12 for gainers/losers (the API considers the differences between periods 12 and 13, and between periods 13 and 14). The trending algorithms require at least 3 periods (with two differences between them), because the API considers the differences, hence periodCount - 3 is the highest firstRankPeriod can be for gainers/losers and other trending algorithms.
algorithmArgument xsd:string
(Optional) Specifies how to order the values for Most Popular, Gainers or Losers. Specify either percent, count or linear. Default is linear.
reportDescriptionDateGranularity An enumerated list of values that specify a time period used to display report data. If you do not specify a dateGranularity parameter for an overtime report, the data will be aggregate and not granularized. Value
Description
seconds
Displays report data for the current minute (Real-Time reports only).
hour
Displays report data for the current hour.
day
Displays report data for the current day.
week
Displays report data for the current week.
month
Displays report data for the current month.
Data Types
27
Value
Description
quarter
Displays report data for the current quarter.
year
Displays report data for the current year.
reportDescriptionElement A structure data type that identifies one element used in a report. Name
Type
Description
id
xsd:string
Specifies the name of the element to apply to the metrics report.
classification
xsd:string
(Optional) Restricts the element results to only those that fall in the specified classification. For example you could set id = "trackingCode" and classification = "Campaigns" to get a report of all tracking codes for the Campaigns classification.
top
xsd:int
(Optional) Specifies the number of rows in the report to return. Use with startingWith to generate paged reports. For example, top=5 returns five rows. The maximum number of top elements that can be requested is 50,000. Setting the "top" parameter to a number greater than 50000 will result in an element_top_invalid error.
startingWith
xsd:int
search
reportDescriptionSearch (Optional) Applies a search to the element.
selected
array(xsd:string)
parentID
xsd:string
checkpoints
array(xsd:string)
pattern
xsd:string[][]
(Optional) Specifies the first row in the report to return. Use with top to generate paged reports. For example, startingWith=20 returns report rows starting at row 20.
(Optional) Defines a specific list of items to request instead of using search, top, and startingWith to set the element parameters. (Optional) Hierarchy report. To specify a specific level to report, add a add a level and parentID parameter. The parentID is returned in report data, making it available to request the next level of the hierarchy. Generates a pathing report. See Pathing Reports Generate a fallout pathing report. See Pathing Reports
reportDescriptionElementDataEncoding An enumerated list of data encoding types.
Data Types
Value base64
utf8
28
Description If base64 encoding is used, the request must also have all element names base64 encoded. This includes names in "selected" and "search" filters, and the "pattern" and "checkpoint" pathing filters. This also applies to special keywords as well, such as "::entered::" and "::anything::". This also includes dates in the "name" field for overtime and trended reports. Element URLs are not encoded. If utf8 encoding is used, the API filters out invalid UTF-8 characters in the request and response. This allows the result to come back with some data, although the values may be missing information.
reportDescriptionElementList An array of reportDescriptionElement.
reportDescriptionLocale An enumerated list of values that specify the language used to display the report data. Value
Description
en_US
English (United States)
de_DE
German (Germany)
es_ES
Spanish (Spain)
fr_FR
French (France)
jp_JP
Japanese (Japan)
pt_BR
Portuguese (Brazil)
ko_KR
Korean (Korea)
zh_CN
Chinese (China)
zh_TW
Chinese (Taiwan)
reportDescriptionMetric A structure that identifies one metric used in a report. Element
Type
id
xsd:string
reportDescriptionMetricList An array of reportDescriptionMetric.
Description The ID of a metric to include in the report.
Data Types
29
reportDescriptionSearch A structure that defines a keyword search to use in the report definition. Name
Type
Description
type
reportDescriptionSearchType
The type of search to use, one of the following values: • and • or • not
keywords
string[]
A list of keywords to include or exclude from the search, based on the type. Keyword values can also leverage the following special characters to define advanced search criteria: * Wild Card (e.g. "page*.html") ^ Starts With (e.g. "^http://") $ Ends With (e.g. ".html$")
searches
reportDescriptionSearch[] A list of subsearches. This allows you to build complex report searches.
reportDescriptionSearchType An enumerated list of boolean values used to link multiple search terms in a report search. Value
Description
AND
Combines multiple search terms using a boolean AND operation.
OR
Combines multiple search terms using a boolean OR operation.
NOT
Combines multiple search terms using a boolean NOT operation (effectively excluding a term from the search).
reportDescriptionSegment A structure that defines an inline segment to use in a reportDescription . Element
Type
id
xsd:string
Description Specifies the existing saved segment ID that you want to apply to a search. Important: In version 1.4, inline segments no longer use the "id" parameter to specify the element as in 1.3. If migrating code from version 1.3, move the element value that was previously in the "id" parameter to the "element" parameter.
Data Types
30
Element
Type
element
xsd:string
search
reportDescriptionSearch
Description Specifies the element (dimension) on which you want to segment. (Optional, provide either a selected value, or a classification and a search value). Search is an array that contains two values: • type: selects the type of search to perform. The following search types are supported: • AND • OR • NOT • keywords: Array of values for which you want to search. The following special characters are supported in keywords: • ^ matches the start of a string • $ matches the end of a string
classification
xsd:string
(Optional, provide either a selected value, or a classification and a search value). Specifies how to integrate the include and an exclude segments.
Unsupported Elements The following elements are not supported for inline segments. • pagedepth • visitnumber • mobilecarrier • hier* • *paths • *fallout
reportDescriptionSegmentList An array of reportDescriptionSegment.
reportDescriptionSource An enumerated list of reporting sources. Value standard realtime
Description Returns a standard report. Returns a Real-Time report.
Data Types
31
reportElement A structure that defines an element that appears in a report. Element
Type
id
xsd:string
name
xsd:string
classification
xsd:string
Description The element ID. This must match the element ID specified in the report description. The element name. The name of the classification that was requested, if applicable.
reportElementInfo
Element
Type
id
string
name
string
Description The id of the element. The friendly name of the element.
reportElementList An array of reportElement.
reportMetric A structure that defines a metric that appears in a report. Element
Type
id
xsd:string
name
xsd:string
type
xsd:string
decimals
xsd:int
forumula
xsd:string
Description The metric ID. This must match the metric ID specified in the report description. The metric name. The metric type, either "number", or "currency". The number of decimal places in the metric values. The formula if the metric is a calculated metric.
Data Types
32
Element
Type
latency
xsd:int
current
xsd:boolean
Description Number of seconds the metric data is latent. True indicates that the metric contains the most recent data available as a result of the currentData flag being set to true in the reportDescription.
reportMetricInfo
Element
Type
id
string
name
string
type
string
decimals
integer
formula
string
Description The id of the metric. The friendly name of the metric. The type of the metric (number, percent, currency, time). The number of decimal places in the metric values. The formula if the metric is a calculated metric.
reportMetricList An array of reportMetric.
reportReportSuite A structure that contains report suite information related to a requested report. Element
Type
id
xsd:string
name
xsd:string
Description The report suite ID. The report suite display name.
Data Types
33
reportResponse A structure data type that returns data associated with a particular report request. Element
Type
waitSeconds
xsd:float
runSeconds
xsd:float
report
report
Description The time in seconds this report waited in the queue before being run. A high value here is indicative of a large amount of report requests for a single company. The time in seconds this report took to process and return data. A high value here is indicative of a complex report or large date range. A structure containing the report data.
reportSegment A structure that identifies a segment that appears in a report. Element
Type
Description
id
xsd:string
name
xsd:string
The element ID. This must match the element ID specified in the report description. The element name.
report_queue_item A structure that contains queue data related to a requested report. Name
Type
Description
reportID
xsd:int
The request ID for the report.
type
xsd:string
Report type being generated, one of the following values: • overtime • trended • trendedplus • ranked • universal
queueTime
xsd:string
status
xsd:string
The time the report was requested (Pacific Time). The processing status of the report, one of the following values:
Data Types
Name
34
Type
Description • waiting • running
priority
xsd:int
estimate
xsd:int
user
xsd:string
The priority in the queue. The estimate in seconds that the report will take to complete. The analytics user who requested the report.
report_queue_item_array A list of report_queue_item.
Analytics Elements
35
Analytics Elements Provides a list of elements available in Analytics. An element is a structure that further breaks down (organizes) the a report's metrics data. For example, you can generate a report that breaks down a page view (metric) report by the Web browsers (element) used to access the page. The resulting report lists page views by Web browser type. As part of the report definition, you can specify the elements to include in the report in a reportDescriptionElement. Permissions Specific users may not have access to certain elements. The metrics returned by GetElements reflect those restrictions. Requesting an element that one doesn't have permission to access will result in a element_inaccessible error. Element Breakdowns The reporting API has two groups of elements: Traffic and Commerce. Elements may only be broken down by elements in the same group, as listed in the "Breakdown Type" column in the table below. Breakdowns are not supported on fallout and pathing reports. You can pass any of these elements to GetElements to get a list of valid breakdowns for a specific element. Element Descriptions Element
Breakdown Type
Description
accountsummary
traffic
Corresponds to the Account Summary report in Analytics.
browser
traffic+commerce
Web browser (for example, Internet Explorer 7.0, Firefox 2.0.8).
browserHeight
traffic
Browser frame height (in pixels).
browserType
traffic
Web browser vendor (for example, Microsoft, Mozilla, Apple).
browserWidth
traffic
Browser frame width (in pixels).
category
commerce
Groups of products, organized into a category.
connectionType
traffic
Internet connection type used to access site.
cookiesEnabled
traffic
Web browser that has cookies enabled.
customerLoyalty
commerce
The Customer Loyalty classification.
domain
traffic+commerce
ISPs and organizations used to access site.
entrypage
commerce
Page used to enter the site.
entryPageOriginal
commerce
Page used to enter the site for the first time.
eVar #
commerce
Specified eVar.
firstTouchChannel
commerce
First touch marketing channel.
firstTouchChannelDetail
commerce
Detailed version of the First touch marketing channel.
geoCountry
traffic+commerce
Country.
geoRegion
traffic+commerce
Geographical region.
geoCity
traffic+commerce
City.
geoDMA
traffic+commerce
Designated Market Area.
Analytics Elements
36
Element
Breakdown Type
hier1-5
traffic
Description Hierarchy report. To specify a specific level to report, add a add a level and parentID parameter to the element structure: { "id":"hier2", "level":"3", "parentID":"75483925" }
The parentID is obtained from the results of the previous level: { "name": "Home Page", "url": "", "counts": ["72"], "parentID": "75483925" }
Not supported by inline segments. javaEnabled
traffic
Web browser that has Java enabled.
javaScriptEnabled
traffic
Web browser that has JavaScript enabled.
javaScriptVersion
traffic
Version of JavaScript used on the Web browser.
language
traffic+commerce
Web browser language.
lasttouchchannel
commerce
Last touch marketing channel.
lasttouchchanneldetail
commerce
Detailed version of the Last touch marketing channel.
linkCustom
traffic
Link usage (user-preferred links).
linkDownload
traffic
Links to downloaded content.
linkExit
traffic
Third-party links where client exits your site.
listVar#
commerce
Specified list variable.
mobileAudioSupport
commerce
Audio formats supported by mobile device.
mobileCarrier
commerce
Mobile service provider. Not supported by inline segments.
mobileColorDepth
commerce
Number of simultaneous display colors supported by mobile device.
mobileCookieSupport
commerce
Mobile device with cookies enabled.
mobileDeviceName
commerce
Mobile device name.
mobileDeviceType
commerce
Mobile device type.
mobileDeviceNumberTransmit commerce
Indicates if Device Number Transmit is On or Off on the mobile device.
mobileDRM
commerce
The type of Digital Rights Management (DRM) supported by the mobile device (Forward Lock, Combined Delivery, Separate Delivery).
mobileImageSupport
commerce
Mobile device with image support enabled.
mobileInformationServices commerce
The information services supported by the mobile device.
mobileJavaVM
The Java version running on the mobile device.
commerce
Analytics Elements
37
Element
Breakdown Type
Description
mobileMailDecoration
commerce
A boolean value that indicates if the mobile device supports Email decorations (animation).
mobileManufacturer
commerce
The mobile device manufacturer.
mobileMaxBookmarkUrlLength commerce
The maximum bookmark URL length supported by the mobile device, in characters.
mobileMaxBrowserUrlLength commerce
The maximum Web browser URL length supported by the mobile device, in characters.
mobileMaxMailUrlLength commerce
The maximum Email URL length supported by the mobile device, in characters.
mobileNetProtocols
commerce
The network protocols supported by the mobile device (GPRS, Edge, etc.)
mobileOS
commerce
The operating system running on the mobile device.
mobilePushToTalk
commerce
Boolean value that indicates if the mobile device supports Push to Talk (PTT).
mobileScreenHeight
commerce
Mobile device screen height (in pixels).
mobileScreenSize
commerce
Mobile device screen size (in inches).
mobileScreenWidth
commerce
Mobile device screen width (in pixels).
mobileVideoSupport
commerce
Mobile device with video support enabled.
monitorColorDepth
commerce
The number of simultaneous display colors supported by the mobile device.
monitorResolution
traffic+commerce
Client's monitor resolution.
operatingSystem
traffic+commerce
Client operating system.
page
traffic+commerce
Page names.
pageDepth
traffic
The visitor's maximum page depth (number of clicks into the Web site), calculated from the landing page. Not supported by inline segments.
pagesNotFound
traffic
The number of times a visitor encountered a missing page (HTTP 404 error).
pathLength
commerce
Number of pages viewed during the visit.
product
commerce
Individual products.
prop #
traffic+commerce
Specified property.
trackingCode
commerce
Campaign tracking code results.
referrer
traffic
Domain or URL that client came from.
referrerType
traffic
Type of referrer. Options include Hard drive, Other Web site, Search engine, Social, andTyped/Bookmarked.
referringDomain
traffic+commerce
Domains that referred client to the site.
referringDomainOriginal
commerce
Domains that referred client to the site on their first visit.
Analytics Elements
38
Element
Breakdown Type
Description
reportSuite
n/a (reportSuite is the only Used to generate report suite summary reports. element on summary reports)
returnFrequency
traffic
Number of clients that return, and how soon they return.
searchEngine
traffic+commerce
Search engine used to locate site.
searchEngineKeyword
traffic+commerce
Search engine keyword used to locate the site.
searchEngineNatural
traffic+commerce
Search engine used to locate the site.
searchEngineNaturalKeyword traffic+commerce
The natural (not paid) search engine keyword used to find the site.
searchEngineNaturalPageRank
Search engine results rank.
searchEnginePaid
traffic+commerce
Search engine with paid result placement.
searchEnginePaidKeyword traffic+commerce
The paid search engine keyword used to find the site.
server
traffic
Pages hosted by the same server.
siteSection
traffic+commerce
Groups of Web pages, organized into a site.
socialterm
commerce
Term selected to identify relevant social content.
socialcontentprovider
commerce
Provider of the social data.
socialauthor
commerce
Content author.
sociallink
commerce
Social link.
socialtermslist
commerce
List of social terms.
socialaveragesentiment
commerce
Sentiment rating of social content.
socialproperty
commerce
A facebook page or application.
socialassettrackingcode
commerce
Asset identifier.
state
commerce
U.S. state.
surveybase
commerce
The unclassified Survey element. Use this element with classifications retrieved via ReportSuite.GetClassifications where c_view = survey.
timePrior
traffic+commerce
Client time zone.
timeZone
traffic+commerce
Client time zone.
timeVisit
traffic+commerce
Duration of client visit.
tntBase
commerce
The unclassified Test & Target element. Use this element with classifications retrieved via ReportSuite.GetClassifications where c_view = tnt.
topLevelDomain
traffic+commerce
Originating domain extension (.com, .net, .gov, .edu, .org, and country extensions).
trackingCode
commerce
Tracking code.
video
commerce
Video name. (v15)
videoad
commerce
Video ad.
videosegment
commerce
Segment name.
Analytics Elements
39
Element
Breakdown Type
Description
videocontenttype
commerce
Content type associated with a video.
videos
commerce
Videos viewed. (v14)
videoPlayers
commerce
Video player used to view videos.
visitNumber
traffic+commerce
Number of visits to site. Not supported by inline segments.
zip
commerce
Client zip code.
Analytics Metrics
40
Analytics Metrics Provides a list of metrics available in Analytics. A metric is a structure that specifies the type of event data captured in the report. Calculated Metrics Calculated metrics are returned along with the other reporting API metrics. The IDs of these metrics are in the form f:
Where is some integer value. The metric type, decimal precision, and formula (where applicable) are included for all metrics. Overtime-Only Metrics Some metrics are only valid in overtime reports. Use Report.GetMetrics with the dateGranularity parameter to programmatically get a list of these metrics. • averagetimespentonsite • averagevisitdepth • customersdaily • customersloyal • customersmonthly • customersnew • customersquarterly • customersreturn • customersweekly • customersyearly • mobileviews • mobilevisitorsdaily • mobilevisits • returnvisits • returnvisitsdaily If you try to run an overtime report on an unsupported metric, a metric_unsupported_in_overtime error occurs. Permissions Specific users may not have access to certain metrics. The metrics returned by GetMetrics reflect those restrictions. Requesting a metric that one doesn't have permission to access will result in a metric_inaccessible error. Metric Descriptions Category Commerce
Metrics
Description
carts
Checkout cart metrics
totalCarts
• Cart Open
lifetimeCarts lifetimeTotalCarts
The number of times a customer opened a shopping cart by adding the first item. Occurs the first time an item is added to the shopping cart. This value comes from the scOpen event.
Analytics Metrics
Category
41
Metrics
Description
participationCarts lifetimeParticipationCarts Commerce
cartAdditions
Checkout cart addition metrics
totalCartAdditions
• Cart Additions
lifetimeCartAdditions lifetimeTotalCartAdditions
The number of times an item was added to a shopping cart. This value comes from the scAdd event.
participationCartAdditions lifetimeParticipationCartAdditions Commerce
cartRemovals
Checkout cart removal metrics
totalCartRemovals
• Cart Removals
lifetimeCartRemovals lifetimeTotalCartRemovals
Number of times an item was removed from a shopping cart. This value comes from the scRemove event.
participationCartRemovals lifetimeParticipationCartRemovals Commerce
cartViews
Checkout cart view metrics
totalCartViews
• Cart Views
lifetimeCartViews lifetimeTotalCartViews
Event in which the contents of the shopping cart are viewed by the customer. This value comes from the scView event.
participationCartViews lifetimeParticipationCartViews Commerce
checkouts
Checkout activity metrics
totalCheckout
• Checkouts
lifetimeCheckout lifetimeTotalCheckouts participationCheckouts lifetimeParticipationCheckouts
Commerce
instances
An event that occurs when customers arrive at the checkout stage of a purchase. The checkout stage usually occurs just before a purchase is finalized, and usually involves the customer entering personal information (such as their shipping and billing information). You have control over the events on your site that qualify as checkouts. This value comes from the scCheckout event. Number of times a specific value is captured. Instances take into account all image request types, and do not factor in conversion variable persistence. For example, if a user arrives on
Analytics Metrics
Category
42
Metrics
Description your site via example.com, the first image request on your site contains the referrer of example.com. Looking at instances in the referrers report shows one Instance attributed to example.com even if this value persists for additional page views or link tracking calls on your site.
Commerce
orders
Order activity metrics
totalOrders
• Orders
lifetimeOrders lifetimeTotalOrders participationOrders
The number of orders made on your website during the selected time period. You can break down individual time periods by other metrics to show the items (such as products or campaigns) that contributed to the most orders during that time frame.
lifetimeParticipationOrders Commerce
revenue
eCommerce revenue metrics
totalRevenue
• Revenue
lifetimeRevenue lifetimeTotalRevenue
Revenue is captured on the purchase event, and is defined as the total dollar amount for the sum of the order for each product. This value comes from the purchase event.
participationRevenue lifetimeParticipationRevenue Commerce
units
Units purchased metrics
totalUnits
• Units
lifetimeUnits lifetimeTotalUnits
The total units that were ordered for the selected time period. Because you have many units purchased per order, Units is a vital metric that reveals general inventory movement.
participationUnits lifetimeParticipationUnits Commerce
customersNew customersReturn customersLoyal customersDaily customersWeekly customersMonthly customersQuarterly customersYearly
Customer metrics
Analytics Metrics
Category Commerce
43
Metrics bounces
Description Pathing Metrics.
bounceRate totalTimeSpent pathviews Commerce
Event#
Custom event metric (1-100)
(for example, event2) Commerce Commerce
mobilecarrier socialmentions
Mobile device metrics Social metrics. Available only if Social is enabled.
socialreach socialtotalsentiment sociallikeadds socialpageviews socialpostviews socialfbstorytellers socialfbstories socialpubrecommends socialpubcomments socialpubsubscribers socialpubposts Commerce
videotime
Video metrics. Available only if v15 video measurement is enabled.
videostart videocomplete videosegmentviews videoadstart videoadcomplete Traffic
mobileViews
Mobile device metrics. Available only if mobile application reporting is enabled.
mobileVisits mobileVisitorsDaily Traffic
pageViews
Page view metrics
Analytics Metrics
Category
44
Metrics
Description
totalPageViews Traffic
visits
Site visit metrics
totalVisits averageTimeSpentOnSite averageVisitDepth returnvisits returnvisitsdaily Traffic
visitors
Site visitor metrics
visitorsNew visitorsHourly totalVisitorsHourly visitorsDaily totalVisitorsDaily visitorsWeekly totalVisitorsWeekly visitorsMonthly totalVisitorsMonthly visitorsQuarterly totalVisitorsQuarterly visitorsYearly totalVisitorsYearly Traffic
videoViews
Video usage metrics
videoVisits videoVisitorsDaily Traffic
averagePageDepth averageTimeSpentOnPage entries exits reloads singleAccess
Pathing metrics
Analytics Metrics
Category Traffic
45
Metrics bots
Description Bot traffic metrics
Valid Element and Metric Combinations
46
Valid Element and Metric Combinations Certain metrics may only be requested along with certain elements. You can pass any element to GetMetrics to get a list of valid metrics for a specific element. Every element has either a metric whitelist or a metric blacklist, whichever is shorter, that determines these restrictions. If you request an invalid combination, a metric_not_supported_for_element error occurs. Elements with Metric Whitelists The elements in the element column can be requested only with the metrics in the right column. Element
Metric Whitelist
*fallout
pageviews
*paths
pageviews
videos
cartadditions, cartremovals, carts, cartviews, checkouts, orders, revenue, units, event*
Elements with Metric Blacklists The elements in the element column can be requested with any metric except for those that appear in the right column. Element
Metric Blacklist
browserheight
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
browsertype
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
browserwidth
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
connectiontype
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
cookiesenabled
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
geocity
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
geocountry
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
geodma
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
georegion
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
hier*
uniquevisitors, visitors
javaenabled
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
javascriptenabled
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
Valid Element and Metric Combinations
47
javascriptversion
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
listvar*
instances
mobilecarrier
videocomplete, videosegmentviews, videostart, videotime
monitorcolordepth
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
pagedepth
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
pagesnotfound
averagepagedepth, averagetimespentonpage, cartadditions, cartremovals, carts, cartviews, checkouts, orders, participationrevenue, participationunits, reloads, revenue, units, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
prop*
averagetimespentonsite, averagevisitdepth, bots, totalcartadditions, totalcartremovals, totalcarts, totalcartviews, totalcheckouts, totalorders, totalpageviews, totalrevenue, totalunits, totalvisitorsdaily, totalvisitorshourly, totalvisitorsmonthly, totalvisitorsquarterly, totalvisitorsweekly, totalvisitorsyearly, totalvisits, videosegmentviews, visitorsnew, totalevent*
referrer
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
referrertype
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
returnfrequency
averagepagedepth, averagetimespentonpage, videocomplete, videosegmentviews, videostart, videotime, event*, participationevent*
searchenginepaid
instances
searchenginepaidkeyword instances server
averagetimespentonsite, averagevisitdepth, bots, totalcartadditions, totalcartremovals, totalcarts, totalcartviews, totalcheckouts, totalorders, totalpageviews, totalrevenue, totalunits, totalvisitorsdaily, totalvisitorshourly, totalvisitorsmonthly, totalvisitorsquarterly, totalvisitorsweekly, totalvisitorsyearly, totalvisits, videosegmentviews, visitorsnew, totalevent*
sitesection
singleaccess
surveybase
instances
tntbase
instances
Analytics Report Error Codes
48
Analytics Report Error Codes Provides a list of error codes that Analytics returns when a report does not generate properly. Numeric error codes have been abandoned in favor of textual, descriptive error messages. The following adjectives in error codes have specific meanings: Adjective
Meaning
invalid
The provided value is wrong in some way. If the user changes it, things will work.
missing
A required value is missing. If the user provides it, things will work.
inaccessible
The user doesn't have permission to access the feature.
unsupported
The particular functionality requested is not supported at this time. It may be supported in the future.
unavailable
The feature requested isn't available. The user can usually fix this but not by changing the report description.
failure
The system has failed and it's not the users fault.
Reporting API 1.4 Errors Code
Message
algorithm_argument_invalid
algorithmArgument must be "linear" or "count"
calculated_metric_invalid
Formula "%s" not found
calculated_metric_invalid
Invalid formula ID "%s"
calculated_metric_invalid
Invalid metric "%s"
calculated_metric_invalid
Metric "%s" in formula "%s" is not found
calculated_metric_unsupported Metric "%s" in formula "%s" is not supported date_granularity_missing
anomalyDetection requires dateGranularity
date_invalid
"%s" is not a valid date
element_classification_invalid Invalid classification "%s" for element "%s" element_combination_unsupported This combination of elements is not supported element_id_invalid
Element "%s" not found
element_id_missing
Element id must be specified
element_inaccessible
You do not have permission to access element "%s"
element_top_invalid
The maximum number of top element values supported is %d
element_search_unsupported
Element search is only supported on the first element for Real Time reports
element_selected_unsupported Element selected is only supported on the first element for Real Time reports element_top_unsupported
"top" is only supported on the primary (last) element for Real Time reports
element_top_invalid
The maximum number of top element values supported is 100
elements_invalid
The maximum number of elements supported is %d
expedite_inaccessible
You do not have permission to expedite this request
fallout_checkpoint_required
Fallout selected checkpoint cannot be empty
Analytics Report Error Codes
49
fallout_invalid
Fallout requires selected items
fallout_invalid
Fallout selected cannot have more than %s checkpoints
fallout_invalid
Fallout selected must have at least %s checkpoints
first_rank_period_invalid
firstRankPeriod must be an integer between 0 and 60
floor_sensitivity_invalid
floorSensitivity must be a valid float between zero and 1
hierarchy_level_invalid
Hierarchy level "%s" is invalid for "%s"
hierarchy_parent_id_missing
Hierarchy parentID is missing for "%s"
metric_id_invalid
Metric "%s" not found
metric_id_missing
Metric id must be specified
metric_inaccessible
You do not have permission to access metric "%s"
metric_not_supported_for_element The element "%s" does not support the metric "%s" metric_unsupported_in_overtime Metric "%s" not supported in overtime reports metric_unsupported_in_ranked Metric "%s" not supported in ranked reports metric_unsupported_in_trended Metric "%s" not supported in trended reports multiple_metrics_unsupported Only one metric is supported for realtime reports multiple_elements_unsupported Only two elements are supported for realtime reports pathing_filter_invalid
Items must be specified after ::not::
pathing_filter_required
Pathing pattern filter cannot be empty
pathing_invalid
Pathing requires selected pattern
period_invalid
both date and dateFrom or dateTo cannot be specified
period_invalid
dateTo must be after dateFrom
period_invalid
Invalid dateGranularity
period_invalid
Year must be between %s and %s
period_missing
dateFrom and dateTo must both be specified
realtime_report_invalid
This report is not configured for realtime
report_not_ready
Report not ready
report_suite_invalid
Invalid report suite "%s"
report_suite_invalid
Report suite "%s" not found
report_suite_missing
reportSuiteID is missing
search_invalid
Search arguments missing
search_operator_invalid
Invalid search operator "%s"
segment_element_invalid
Element "%s" not valid for inline segment
segment_element_invalid
Segment element "%s" not found
segment_inaccessible
You do not have permission to access this segment
segment_invalid
Segment definition missing
Analytics Report Error Codes
50
segment_missing
You must specify a segment
segment_unsupported
Segment element "%s" not supported
segment_unsupported
Segment search keywords are only supported on classifications
segment_unsupported
Segment search not supported
sort_method_invalid
"sortMethod" must be gainers, losers, or mostpopular
system_failure
A system failure has occurred
Anomaly Detection
Anomaly Detection Anomaly detection provides a statistical method to determine how a given metric has changed in relation to previous data. To retrieve anomaly detection data, set anomalyDetection to true in reportDescription. Data is returned in the following format for trended reports: { "name": "Tue. 31 Jul. 2012", "year": 2012, "month": 7, "day": 31, "counts": [ "45" ], "upper_bounds": [ "52" ], "lower_bounds": [ "14" ], "forecasts": [ "33" ], "breakdown_total": [ "99" ] }
data is returned in the following format for overtime reports: { "name": "Mon. 30 Jul. 2012", "year": 2012, "month": 7, "day": 30, "counts": [ "45", "50.89" ], "upper_bounds": [ "67", "43" ], "lower_bounds": [ "44", "32" ], "forecasts": [ "56", "54" ] }
51
Inline Segmentation
52
Inline Segmentation Inline segmentation allows you to segment report data using segment definitions that are include as part of the reportDescription : • Segment by specific line items (only include data where page = "Home Page") • Segment classified values by search criteria (only include data where a classification of evar1 matches a search) Note the following limitations: • Segments are based on a page view container. • A maximum of 10,000 values are returned when you define an inline segment. If you encounter this limitation, either reduce the scope of the report or use a regular segment. • Some reports are not supported by inline segments. A complete list is at the bottom of this article. • Prop values cannot be used to define inline segments. Important: In version 1.4, inline segments no longer use the "id" parameter to specify the element as in 1.3. If migrating code from version 1.3, move the element value that was previously in the "id" parameter to the "element" parameter. Segmenting by Line Items Create a segment definition with an id of the reporting element you want to segment, with a selected value that contains the match criteria. { "reportDescription": { "reportSuiteID": "rsid", "date": "2013-09-01", "metrics": [ { "id": "pageviews" } ], "elements": [ { "id": "browser" } ], "segments": [ { "element": "page", "selected": ["Home Page", "Shopping Cart"] } ], } }
This report shows the page views for every browser when the page name is either "Home Page" or "Shopping Cart". Segmenting by Classification Value Create a segment definition with an id of the reporting element you want to segment, the classification you want to match, and a search string. { "reportDescription": { "reportSuiteID": "rsid", "date": "2013-09-01", "metrics": [ { "id": "pageviews" } ], "elements": [ { "id": "browser" } ], "segments": [ {
Inline Segmentation
53
"element": "eVar1", "classification": "Group Name", "search": { "type": "OR", "keywords": ["Administrator", "Manager", "Director"] } } ], } }
This report shows the page views for every browser when the "Group Name" classification of eVar1 contains "Administrator, "Manager", or "Director". The following search types are supported: • AND • OR • NOT The following special characters are supported in keywords: • ^ matches the start of a string • $ matches the end of a string Multiple Segments You can provide multiple segments in the segments array. Segments are joined using AND. Segments cannot be nested. "segments": [ { "element": "page", "selected": ["Home Page", "Shopping Cart"] }, { "element": "eVar1", "classification": "Group Name", "search": { "type": "OR", "keywords": ["Administrator", "Manager", "Director"] } } ]
Including this segment definition in a report shows metrics where the page name is either "Home Page" or "Shopping Cart", and the "Group Name" classification of eVar1 contains "Administrator, "Manager", or "Director". Examples The following table contains an example of the different search types available with inline segmentation. Classification Search Type
Search Example
Equals
"search": { "type": "AND", "keywords": ["^key$"] }
Does not contain
"search": { "type": "NOT", "keywords": ["^key$"] }
Contains
"search": { "type": "AND", "keywords": ["key word"] }
Contains all of
"search": { "type": "AND", "keywords": ["key", "word"] }
Contains at least one of
"search": { "type": "OR", "keywords": ["key", "word"] }
Does not contain
"search": { "type": "NOT", "keywords": ["key"] }
Is null Is not null
N/A. Empty classifications are not matched by a search. Run a report on the selected element and classification.
Inline Segmentation
54
Starts with
"search": { "type": "AND", "keywords": ["^key"] }
Does not start with
"search": { "type": "NOT", "keywords": ["^key"] }
Ends with
"search": { "type": "AND", "keywords": ["key$"] }
Does not end with
"search": { "type": "NOT", "keywords": ["key$"] }
Unsupported Reports Inline segments cannot be applied to the following report data: • Pathing reports • Mobile carrier • Clickmap • GeoSegmentation Region, City, and U.S. DMA Reports • Hierarchies • Clicks to page • Time spent on page • Time spent on site • Visit depth • Visit number • Keyword URLs • Return visits
Real-Time Reports
55
Real-Time Reports Real Time API reports let you view orders, revenue, units, custom events, instances, and other metrics with up to three correlated dimensions to create granular, real time dashboards with seconds of latency. Real-time reports are available for a rolling 22 previous hour period. Real time reports operate most efficiently with frequent requests. We recommend between 15-30 seconds between updates. Step
Task
Details
1
(Optional) Get current real Call ReportSuite.GetRealTimeSettings time configuration You'll receive a struct with the current configuration, similar to the following: { "real_time_settings":[ { "min_granularity":1, "metric":"instances", "elements":[ "prop2", "searchenginekeyword" ] } ] }
2
Save a new configuration
Call ReportSuite.SaveRealTimeSettings Send in a real_time_settings structure with the metrics and elements from the table in the next section that you would like to enable for real time reports. You can provide a single metric with up to three correlated elements. Note that you do not need to include each correlated element for every report. For example, based on the struct in step one, you can report searchenginekeyword instances without reporting prop2 instances. Realtime configuration changes take 15 minutes to be reflected in reports. Note: If the ui_report parameter is set to false, you must save at least one element and one metric or the configuration will be invalid, even though an error does not occur. If the ui_report parameter is set to true, you must save three elements and one metric or you will receive an error.
3
Run a real time report
Call Report.Run and set the "source" parameter to "realtime". { "reportDescription": { "source": "realtime", "reportSuiteID": "rsid", "metrics": [ { "id": "revenue" } ] } }
Real-Time Reports
56
Minute Granularity When requesting a Real-Time report, you can provide a "dateGranularity" of "minute:[interval]". The interval is an integer between 1-60 that specifies the interval to report. For example, 'minute:3' reports the request date range in 3-minute intervals. Relative Dates Real-Time Reports support relative dates for the Date, DateFrom, and DateTo parameters. For example, to report revenue between noon today and the current time in 3-minute intervals, you could use the following reportDescription: { "reportDescription": { "source": "realtime", "dateFrom": "noon", "dateTo": "now", "dateGranularity": "minute:3", "reportSuiteID": "rsid", "metrics": [ { "id": "revenue" } ] } }
Sort Options Real-Time reports provide a number of sort options that are described in SortMethod Options. { "reportDescription": { "source": "realtime", "reportSuiteID": "rsid", "sortMethod": "mostpopular:.25:0:linear", "metrics": [ { "id": "revenue" } ] } }
Totals for Items not Displayed (Everything Else) You can include an optional "everythingElse" element to return metric totals for elements that are not included in the report. For example, if most popular is selected, this returns totals for values that are not in the most popular list. { "reportDescription": { "source": "realtime", "reportSuiteID": "rsid", "sortMethod": "mostpopular:.25:0:linear", "metrics": [ { "id": "revenue" } ], "elements":[ { "id":"product", "everythingElse": true } ] } }
Supported Metrics and Elements The following table contains a list of the supported metrics and breakdowns available in Real Time Reports.
Real-Time Reports
57
Metrics
Elements
pageviews
page
revenue
product
orders
sitesection
units
server
carts
linkdownload
cartviews
linkexit
instances
linkcustom
checkouts
topleveldomain
cartadditions
referringdomain
cartremovals
searchengine
events1-100
searchenginekeyword
videotime
searchenginenatural
videostart
searchenginepaid
videocomplete
geocountry
videosegmentviews
georegion
videoadstart
geocity
videoadcomplete
geodma
socialmentions
prop1-75
socialtotalsentiment
evar1-75
sociallikeadds
surveybase
socialpageviews
listvar1
socialpostviews
listvar2
socialfbstorytellers
listvar3
socialfbstories
listvar4
socialpubrecommends
video
socialpubcomments
videoad
socialpubsubscribers
videosegment
socialpubposts
videocontenttype
mobileinstalls
socialterm
mobileupgrades
socialcontentprovider
mobiledailyengagedusers
socialauthor
Real-Time Reports
58
Metrics
Elements
mobilemonthlyengagedusers
sociallanguage
mobilelaunches
sociallatlong
mobilecrashes
socialassettrackingcode
mobileprevsessionlength
mobileinstalldate mobileappid mobilelaunchnumber mobiledayssincefirstuse mobiledayssincelastuse mobilehourofday mobiledayofweek mobileosenvironment mobiledayssincelastupgrade mobilelaunchessincelastupgrade mobiledevice mobileosversion mobilegooglecampaignsource mobilegooglecampaignmedium mobilegooglecampaignterm mobilegooglecampaigncontent mobilegooglecampaignname
Summary Reports
59
Summary Reports Summary reports provide high-level metrics for several report suites in a single report. Summary reports do not contain the "reportSuiteID" parameter, instead the report suite is specified as the "reportsuite" report element, and the "selected" parameter contains a list of report suite IDs. The "metrics" parameter contains the metrics you want to report for the specified report suites. // // // //
Summary Report Note that the "reportSuiteID" parameter is not included and the elements list contains "reportsuite" Report suites are provided in the "selected" element
{ "reportDescription":{ "date":"2014", "metrics":[ { "id":"pageviews", }, { "id":"revenue", }, ], "elements":[ { "id":"reportsuite", "selected":[ "rsid1", "rsid2" ] } ], } }
Example response: { "report":{ "type":"summary", "elements":[ { "id":"reportsuite", "name":"Report Suite" } ], "reportSuite":{ "id":"rsid1", "name":"Report Suite 1" }, "period":"2014", "metrics":[ { "id":"pageviews", "name":"Page Views", "type":"number", "decimals":0 }, { "id":"revenue", "name":"Revenue", "type":"currency", "decimals":2 } ], "data":[
Summary Reports
60
{ "name":"rsid1", "url":"", "counts":[ "562166", "0.00" ] }, { "name":"rsid2", "url":"", "counts":[ "484560", "41265.00" ] } ], "totals":null, "version":"1.4.14.5" } }
Pathing Reports
61
Pathing Reports There are two kinds of pathing reports, "Pathing" and "Fallout". Pathing Report (the "pattern" parameter) A pathing report is generated by combining up to five patterns in a list to specify a match. For example: Next Page Report "pattern": [ ["videoPage5"], ["::anything::"] ]
The first pattern matchs the page named videoPage5, the next pattern matches any page. Previous Page Report "pattern": [ ["::anything::"], ["videoPage5"] ]
Next Page Flow Report "pattern": [ ["videoPage5"], ["::anything::"], ["::anything::"], ["::anything::"], ["::anything::"] ]
Not "pattern": [ ["::anything::"], ["::not::","videoPage5","videoPage6"] ]
Special Page Names Using the names of pages on you site along with the special page names in the following table, you can generate a number of useful pathing reports. Value
Meaning
::anything::
Any page, including entered and existed
::not_entered::
Anything except entered the site
::not_exited::
Anything expect exited the site
::entered::
Entered the site
::exited::
Exited the site
::not::
Used before a pagename(s) to negate it. IE. "::not::","page1"
Fallout Report (the "checkpoints" parameter) Fallout reports can be generated for the pageviews metric using page, sitesection, or a prop (if pathing is enabled). To generate a fallout report, provide a list of up to 8 values to use as checkpoints. The number of pageviews returned for each checkpoint indicates the number of pageviews that successfully satisfied all checkpoints up to and including that point.
Pathing Reports
62
Example request: { "reportSuiteID": "rsid", "dateFrom": "2014-01-01", "dateTo": "2014-01-02", "metrics": [ { "id": "pageviews" //This metric is required for all fallout reports. It is the only metric currently supported. } ], "elements": [ { "id": "page", //Only 1 element can be specified. Valid elements are page, sitesection, and prop## (if pathing enabled). "checkpoints": [ //This is the list of checkpoints (Maximum 8 items) "videoPage3", "videoPage2", "videoPage1" ] } ], "locale": "en_US" }
Example response: { "type": "fallout", "elements": [ { "id": "page", "name": "Page" } ], "reportSuite": { "id": "rsid", "name": "my report suite" }, "period": "Wed. 1 Jan. 2014 - Thu. 2 Jan. 2014", "metrics": [ { "id": "pageviews", "name": "Page Views", "type": "number", "decimals": 0, "latency": 205, "current": false } ], "data": [ { "name": "videoPage3", "url": "http://example.com/videoPage3", "counts": [ "191" //This is the total number of visits ] }, { "name": "videoPage2", "url": "http://example.com/videoPage2", "counts": [ "53" //This is the number of visits that continued (27%) ] //Meaning that 130 exited the site (73%) }, { "name": "videoPage1", "url": "http://example.com/videoPage1",
Pathing Reports
"counts": [ "20" ]
63
//This is the number of visits that continued (37%) //Meaning that 33 exited the site (63%)
} ], "totals": null, "version": "1.4" }
Examples //Pathing Report -- NextPage Flow https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "top":"10", "startingWith":"1", "pattern":[ ["homepage"], ["::anything::"], ["::anything::"], ["::anything::"], ["::anything::"] ]} ] } } //Pathing Report -- PreviousPage Flow https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "pattern":[ ["::anything::"], ["::anything::"], ["::anything::"], ["::anything::"], ["homepage"], ]} ] } } //Pathing Report -- Fallout https://api.omniture.com/admin/1.4/rest/?method=Report.Queue { "reportDescription":{ "reportSuiteID":"rsid", "metrics":[ {"id":"pageviews"} ], "elements":[ {"id":"page", "checkpoints":[ "homepage", "/templates/choose-your-powerpoint-fonts-wisely/" ]}
Pathing Reports
] } }
64
View more...
Comments
