Overview
|
Note
|
DRAFT - WORK IN PROGRESS. This guide is compiled from dynamically-generated documentation from code, mixed with human-written documentation snippets, thus there may be some information that is not yet well documented and so it is missing from this guide or shows incomplete. Please feel free to provide feedback to help us improve this guide. |
The purpose of this guide is to help you learn how to use the Adobe Analytics Services APIs by describing the endpoints, their parameters, and responses, as well as provide some examples. It is intended to help answer the common questions of Adobe internal groups working or planning to work with the Analytics Services APIs. It is not intended for use by third parties outside of Adobe.
It is assumed that you have an understanding of the Adobe Analytics product, its features and capabilities and know how to use the product. Thus an introduction to Adobe Analytics, is outside of the scope of this guide. For more information about Adobe Analytics, the product, please refer to the [Adobe Analytics documentation](https://marketing.adobe.com/resources/help/en_US/analytics/getting-started/).
Adobe Analytics Services is a collection of APIs that power Adobe Analytics products like Adobe Analytics Workspace, Adobe Adhoc Analysis, and others. The APIs allow for the creation of data rich user interfaces that customers can use to slice and dice their data. Customers can create reports that explore their data and can get insights into their data or answer important questions about their data.
The APIs allow a wide range of reporting capabilities. With them you can create reports, specify the metrics and dimensions that you want in the report and what date range to request the data for. Further more you can segment the results by using creating and managing segments that can be applied to any report. In addition you can create and manage calculated metrics from basic metrics, dimensions and segmetns that can be utilized in reports just as any regular metric or dimension.
Version information
Version : v1 - Build: 2018-06-26_17:56:41.805
URI scheme
Host : analytics.adobe.io
Schemes : HTTPS
Tags
-
approvals : Operations on approvals
-
calculatedmetrics : Calculated Metrics
-
classifications : Classifications
-
collections : Analytics Collections
-
companies : Analytics Company Service
-
dimensions : Dimensions service
-
favorites : Operations on managing favorites on components
-
metrics : Retrieves a List of Metrics for the Given Report Suite
-
reports : Ranked reports service
-
reportsuites : Analytics Report Suite Service
-
segments : These operations manage Adobe Analytics Segments
-
tags : Operations on tags
-
timezones : Timezone Operations
-
virtualreportsuites : Operations on virtual report suites
Getting Started
Create your OAuth client
-
Navigate to the following URL: https://console.adobe.io/integrations
-
Click the
New Integration
button -
Select the
Access an API
option and then clickContinue
-
Under the Experience Cloud section select
Adobe Analytics
and then selectOAuth integration
and then clickContinue
-
Select
New integration
and then clickContinue
-
Fill out the name, description and other fields and then click
Create Integration
-
Your client is now created. Notice your client has an API Key (Client ID) and a Client secret. These will be needed to get your auth code and to generate access tokens.
Get an auth code using your new client
-
Copy the
Client ID
from your OAuth client and replaceINSERT_CLIENT_ID_HERE
in the following URI with it:
https://ims-na1.adobelogin.com/ims/authorize?client_id=INSERT_CLIENT_ID_HERE&redirect_uri=INSERT_REDIRECT_URI_HERE&scope=openid,AdobeID,read_organizations,additional_info.job_function,additional_info.projectedProductContext&response_type=code
-
Replace
INSERT_REDIRECT_URI_HERE
with your redirect URI you setup when creating the client -
Paste this URL into your favorite browser
-
After authenticating via IMS there will be a code query parameter in the URI. (code=eyJ4…)
-
Copy this code to your clip-board
Generate an access token
-
Replace
INSERT_CODE_HERE
with the code you copied from the previous step in the following curl request:
curl --data "grant_type=authorization_code&client_id=INSERT_CLIENT_ID_HERE&client_secret=INSERT_CLIENT_SECRET_HERE&code=INSERT_CODE_HERE" https://ims-na1.adobelogin.com/ims/token/v1
-
Copy client id from newly created OAuth client and replace
INSERT_CLIENT_ID_HERE
in the curl request -
Copy client secret from newly created OAuth client and replace
INSERT_CLIENT_SECRET_HERE
in the curl request -
Run the curl command
-
You will get a response with an
access_token
attribute in the response. Example response below:
{
"account_type": "type1",
"utcOffset": "null",
"preferred_languages": [
"en-us"
],
"displayName": "Bob Ross",
"last_name": "Ross",
"token_type": "bearer",
"userId": "BOBROSS@AdobeID",
"access_token": "eyJ4...TOKEN_OMITTED",
"emailVerified": "true",
"phoneNumber": null,
"countryCode": "US",
"name": "Bob Ross",
"mrktPerm": "EMAIL:false",
"mrktPermEmail": "false",
"expires_in": 86399988,
"first_name": "Bob",
"email"<EMAIL_ADDRESS>...
}
-
Copy the access token to your clip-board
Test your access token by calling the Analytics APIs
-
Replace
INSERT_ACCESS_TOKEN_HERE
with the access token you copied from the previous step in the following curl request:
curl -X GET --header "Accept: application/json" --header "x-api-key: INSERT_CLIENT_ID_HERE" --header "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" "https://analytics.adobe.io/discovery/me"
-
Replace
INSERT_CLIENT_ID_HERE
with your client ID -
Run the curl command
-
You should get back a response similar to the following:
{
"imsUserId": "1B..OMITTED..01@AdobeID",
"imsOrgs": [
{
"imsOrgId": "EA..OMITTED..29@AdobeOrg",
"companies": [
{
"globalCompanyId": "testco0",
"companyName": "Test Company",
"apiRateLimitPolicy": "aa_api_tier10_tp"
},
{
"globalCompanyId": "anothe0",
"companyName": "Another Test Company",
"apiRateLimitPolicy": "aa_api_tier10_tp"
}
]
},
...
]
}
-
Locate the Company you would like to use to call the Analytics APIs
-
Copy the
globalCompanyId
for the Company you would like to use and replaceINSERT_GLOBAL_COMPANY_ID_HERE
in the following curl request (NOTE:INSERT_GLOBAL_COMPANY_ID_HERE
is included in two places in the request. #1 - In thex-proxy-company-global-company-id
header and #2 - In the path):
curl -X GET --header "Authorization: Bearer INSERT_ACCESS_TOKEN_HERE" --header "x-proxy-company-global-company-id: INSERT_GLOBAL_COMPANY_ID_HERE" --header "x-api-key: INSERT_CLIENT_ID_HERE" "https://analytics.adobe.io/api/INSERT_GLOBAL_COMPANY_ID_HERE/users/me"
-
Replace
INSERT_ACCESS_TOKEN_HERE
with the access token you used in the previous request -
Replace
INSERT_CLIENT_ID_HERE
with your client ID -
Run the curl command
-
You should get a response with information about your analytics user
Now you can use your access token
, global company id
and client ID
to make calls to the APIs. The following Swagger UI provides an easy way to explore calling the various Analytics APIs: https://adobe-experience-cloud.github.io/analytics-2.0-apis/
Ranked Endpoint User Guide
The /ranked
endpoint is the primary endpoint for reporting requests. In order to provide maximum flexibility, many configuration options are available for requests.
Overview
Using the Adobe Analytics UI can help an analyst or digital marketer answer some key questions. Sometimes though, it makes more sense to automate reporting for executive dashboards, custom reporting platforms, or tight Experience Cloud integrations. The Analytics API strives to make these things possible.
It uses the same reporting API as the Analysis Workspace UI within Adobe Analytics.
Best Practices
-
Multiple smaller requests are preferred and often perform better than a single large request
-
Request data once and cache it
-
Don’t poll for new data faster than a 30 minute interval
-
Pull historical data and increment it regularly instead of requesting the entire data set
Discouraged Practices:
-
Requesting as much data as possible in a single request
-
Requesting one year of data at day granularity everyday - just request the new day and merge it
-
Driving a web page with a site performance widget by making an API request every time the web page is loaded
-
Requesting a full year of day-level data every day to get a rolling 12-month window
Time Series Data
Time Series reports are the simplest report that the API can produce. They simply include information about the performance of a metric (or metrics) over a period of time.
Here is a simple 'Page Views' request:
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ], "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ] }, "dimension":"variables/daterangeday", "settings":{ "dimensionSort":"asc" } }
This report can be run with a curl
command on the commandline:
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d '[REQUESTJSON]' "[analytics_services_base_url]/reports/ranked?locale=en_US"
This request is doing a few things:
-
Requesting the Page Views metric for the report suite
adbedocrsid
-
From Dec. 31, 2017 00:00:00.000 - Jan. 06, 2018 23:59:59.999 (using the report suite timezone)
-
Using
variables/daterangeday
granularity (there are seven days in this time period, so I’ll expect seven numbers) -
Sort by ascending date (i.e., oldest to newest)
Example response:
{ "totalPages":1, "firstPage":true, "lastPage":false, "numberOfElements":7, "number":0, "totalElements":7, "columns":{ "dimension":{ "id":"variables/daterangeday", "type":"time" }, "columnIds":[ "0" ] }, "rows":[ { "itemId":"1171131", "value":"Dec 31, 2017", "data":[ 794.0 ] }, { "itemId":"1180001", "value":"Jan 1, 2018", "data":[ 16558.0 ] }, { "itemId":"1180002", "value":"Jan 2, 2018", "data":[ 17381.0 ] }, { "itemId":"1180003", "value":"Jan 3, 2018", "data":[ 17384.0 ] }, { "itemId":"1180004", "value":"Jan 4, 2018", "data":[ 17442.0 ] }, { "itemId":"1180005", "value":"Jan 5, 2018", "data":[ 17417.0 ] }, { "itemId":"1180006", "value":"Jan 6, 2018", "data":[ 17334.0 ] } ], "summaryData":{ "totals":[ 104310.0 ] } }
The JSON response is made up of a few sections:
-
The
rows
section contains each report record. In the above example, we see seven rows, each with avalue
anddata
array. -
The
value
property contains the dimension value. Since we’re requesting a page views total by day, the value of each row will contain a date identifier for the day. For time series data, this identifier will change based on the granularity. For example, if we requestedvariables/daterangemonth
instead, each value would contain a month/year identifier. -
The
data
property contains a list of metric counts for each metric requested. Since only one metric was requested, we only have a single total in each row. -
The
summaryData
section contains a total of the metrics in the current report.
A few handy changes:
* Set dimension
to variables/daterageday
for day granularity
* Change the id
property in the metrics
section to metrics/visits
to request visits instead
Pagination
If we wanted to paginate the results, we would need to add a limit
and page
parameter to the settings
object:
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-31T23:59:59.999" } ], "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-31T23:59:59.999" } ] }, "dimension":"variables/daterangeday", "settings":{ "dimensionSort":"asc", "limit":"10", "page":"2" } }
Anomaly Detection
The API can also produce information about anomalies that occur in a metric for a given time period. This is the same information provided in the UI and is provided by building a model based on historical performance and calculating confidence bands for expected performance. In other words, if the metric value is within the upper and lower bound of the confidence bands, that value is within observed historical norms.
While this information is available from the 1.4 API, a notable difference is the new inclusion of hour-based granularity. This can be very useful for building alerting tools or dashboards.
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ], "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ] }, "dimension":"variables/daterangeday", "settings":{ "dimensionSort":"asc", "includeAnomalyDetection":true } }
Example Response:
{ "totalPages":1, "firstPage":true, "lastPage":false, "numberOfElements":7, "number":0, "totalElements":7, "columns":{ "dimension":{ "id":"variables/daterangeday", "type":"time" }, "columnIds":[ "0" ] }, "rows":[ { "itemId":"1171131", "value":"Dec 31, 2017", "data":[ 794.0 ], "dataExpected":[ 17395.648628666 ], "dataUpperBound":[ 17462.569820465 ], "dataLowerBound":[ 17328.727436868 ], "dataAnomalyDetected":[ true ] }, { "itemId":"1180001", "value":"Jan 1, 2018", "data":[ 16558.0 ], "dataExpected":[ 17374.697042688 ], "dataUpperBound":[ 17444.125385086 ], "dataLowerBound":[ 17305.26870029 ], "dataAnomalyDetected":[ true ] }, ...SNIP... ], "summaryData":{ "totals":[ 104310.0 ] } }
Let’s look at one of these records:
{ "itemId":"1180004", "value":"Jan 4, 2018", "data":[ 17442.0 ], "dataExpected":[ 17367.596716078 ], "dataUpperBound":[ 17438.041586498 ], "dataLowerBound":[ 17297.151845658 ], "dataAnomalyDetected":[ true ] },
There are four properties:
-
dataExpected
- The calculated expected value for the metric -
dataUpperBound
- The upper limit of the confidence band -
dataLowerBound
- The lower limit of the confidence band -
dataAnomalyDetected
- An indicator of whether the metric value is outside of the confidence bands.
Trended and Ranked Requests
The above overtime examples could be seen as a 'Ranked' report, in that the dimension
that was used was the date. With that in mind, let’s try replacing the dimension
with something else.
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ], "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ] }, "dimension":"variables/evar1", "settings":{ "dimensionSort":"asc", "limit":5 } }
Here, I’m requesting evar1
. In this example, the evar is simply storing a numeric ID for a campaign. Here is the example output:
{ "totalPages":8, "firstPage":true, "lastPage":false, "numberOfElements":5, "number":0, "totalElements":40, "columns":{ "dimension":{ "id":"variables/evar1", "type":"string" }, "columnIds":[ "0" ] }, "rows":[ { "itemId":"0", "value":"Unspecified", "data":[ 11560.0 ] }, { "itemId":"219343969", "value":"15", "data":[ 524.0 ] }, { "itemId":"349230650", "value":"7", "data":[ 4420.0 ] }, { "itemId":"511036305", "value":"11", "data":[ 1631.0 ] }, { "itemId":"743855946", "value":"10", "data":[ 2032.0 ] } ], "summaryData":{ "totals":[ 104310.0 ] } }
Let’s look in detail at one of the records returned:
{ "itemId":"743855946", "value":"10", "data":[ 2032.0 ] },
-
itemId
- This is the unique ID associated with this particular value - in this case, campaign "10". -
value
- This contains the value of the evar. -
data
- This is an array of counts - one for each metric requested.
Filters
In the above example, only the top 5 records were requested and there were 8 pages worth of data available — only 40 records. What if there were thousands of records, and only a handful were being reported on? Filters can be used to only include those few valuable values in the report.
For the next example, let’s only request data for campaigns "10" and "11" by using their itemIds.
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ], "search":{ "itemIds":[743855946,511036305] }, "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ] }, "dimension":"variables/evar1", "settings":{ "dimensionSort":"asc", "limit":5 } }
Example response:
{ "totalPages":1, "firstPage":true, "lastPage":true, "numberOfElements":2, "number":0, "totalElements":2, "columns":{ "dimension":{ "id":"variables/evar1", "type":"string" }, "columnIds":[ "0" ] }, "rows":[ { "itemId":"511036305", "value":"11", "data":[ 1631.0 ] }, { "itemId":"743855946", "value":"10", "data":[ 2032.0 ] } ], "summaryData":{ "totals":[ 104310.0 ] } }
The search parameter allows many parameters:
-
itemId
- A single ID to include in the report -
itemIds
- A list of itemIds to include in the report (shown in the example) -
excludeItemIds
- A list of itemIds to exclude in the report -
clause
- A search clause to use when filtering dimensions -
includeSearchTotal
- Includes a special element called 'searchTotals' in the response that contains the total of the filtered items. The default is false.
Clause
The search clause
parameter provides a very powerful tool for filtering data.
-
Uses boolean operators
AND
,OR
, andNOT
-
Uses operators
MATCH
,CONTAINS
,BEGINS-WITH
,ENDS-WITH
-
Group conditions using parenthesis
-
Strings are contained in single quotes.
-
Searches are case-insensitive
-
If no operator is specified, a 'contains' match is performed
-
Valid operators are 'match' and 'contains'
-
Glob expressions are evaluated. If a literal
is needed, use
\
When searching the for page names, do the following:
Only include results that match the string 'home page':
MATCH 'home page'
Include pages that don’t contain 'home page':
NOT CONTAINS 'home page'
Include pages that don’t contain 'home page' or 'about us', but do contain 'contact us':
(NOT CONTAINS 'home page' OR NOT CONTAINS 'about us') AND (CONTAINS 'contact us')
Include pages that contain 'home page' or start with 'landing':
CONTAINS 'home page' OR BEGINS-WITH 'landing'
Applying a Segment
You can include a segment in your report by adding it to the globalFilters
property.
... "globalFilters":[ { "type":"dateRange", "dateRange":"2014-06-01T00:00/2014-06-21T00:00" }, { "type":"segment", "segmentId":"53adb46be4b0a2a175bf38c4" } ], ...
Breakdown Requests
Breakdowns in the API can be useful when you want to see the cross-product of values from two different dimensions. For example — see a report containing a list of the top "Internal Search Terms" used by visitors who saw campaign "10".
To request a breakdown report, you’ll use the metricsFilters
and dimension
parameters to request the additional dimension. In the below example, evar1
is the marketing campaign and evar2
is the "Internal Search Terms".
{ "rsid":"adbedocrsid", "globalFilters":[ { "type":"dateRange", "dateRange":"2017-12-31T00:00:00.000/2018-01-06T23:59:59.999" } ], "metricContainer":{ "metrics":[ { "columnId":"0", "id":"metrics/pageviews", "filters":[ "0" ] } ], "metricFilters":[ { "id":"0", "type":"breakdown", "dateRange":"evar1", "itemId":"743855946" } ] }, "dimension":"variables/evar2", "settings":{ "dimensionSort":"asc", "limit":5 } }
Example Response:
{ "totalPages":2, "firstPage":true, "lastPage":false, "numberOfElements":5, "number":0, "totalElements":7, "columns":{ "dimension":{ "id":"variables/evar2", "type":"string" }, "columnIds":[ "0" ] }, "rows":[ { "itemId":"1132341824", "value":"red t-shirt", "data":[ 1515.0 ] }, { "itemId":"2400044733", "value":"digital watches", "data":[ 1.0 ] }, { "itemId":"3351316813", "value":"sport socks", "data":[ 11.0 ] }, { "itemId":"3440395251", "value":"gps watch", "data":[ 95.0 ] }, { "itemId":"3614317595", "value":"running shoes", "data":[ 16.0 ] } ], "summaryData":{ "totals":[ 2032.0 ] } }
Segments Endpoint User Guide
The /segments
endpoint can be used to programmatically manage segments in Adobe Analytics. Segments allow the user to isolate an interesting set of visitors, visits, or hits. Once isolated, a more thorough analysis can be performed, or actions can be taken by sharing it with other Adobe Experience Cloud products.
For information about segments and how they work, please see this documentation: https://experiencecloud.adobe.com/resources/help/en_US/analytics/segment/seg_workflow.html
Segment Definition Data Structure
The segment definition data structure is used to communicate segment rules to the API. This data structure defines the raw logic that will be used to isolate the segment data. The segment definition data structure is a hierarchical data structure of containers, functions, and boolean logic that is used to define the segment. The segment tool in the Adobe Analytics UI follows these rules and can be a useful tool for understanding how the data structure looks. Below is an example segment definition for your reference.
Terms
-
Schema - Refers to a report suite’s configuration. Identifies which dimensions and metrics are available for use within the segment.
-
Attribute - An entity in the schema. For example,
page
orevar1
. -
Context - Defines the level that the segment logic should operate on. Valid values are
visitors
,visits
, andhits
. -
Row - A single record of data in a segment. Depending on the context, this can either be a record containing a visitor (contains all hits in all visits for a visitor), a single visit (contains all hits in a visit), or a single hit.
-
Container - A collection of rows
-
Container Set - Identifies the relationship between containers using boolean expressions.
-
Data Set - A group of collections that comprises all of the data being operated on.
Let’s use the following segment example to go in-depth on what each of these terms mean and how they’re used.
{ "definition":{ "func":"segment", "container":{ "func":"container", "context":"hits", "pred":{ "func":"exists", "description":"Page", "val":{ "func":"attr", "name":"variables/page" } } }, "version":[1,0,0] } }
Schema
This is a reflection of the Adobe Analytics implementation. In other words, it defines the configuration for the enabled evars, props, events, etc.
Attributes
An attribute is an entity from the schema. In the above example, variables/page
is an attribute.
Context
The rules in a segment have a context that tells them at what level to operate at. The context can be visitors
, visits
or hits
.
As an example, let’s build a segment rule where revenue is greater than 0 (meaning a purchase took place) and change the context to see how things change.
If the context is set to visitors
, the segment will include all hits from visitors that have a purchase of some kind during a visit. This could be useful in analyzing customer behavior in visits leading up to a purchase and possibly behavior after a purchase is made.
If the context is set to visits
, the segment will include all hits from visits where a purchase occurred. This could be useful for seeing the behavior of a visitor in immediate page views leading up to the purchase.
If the context is set to hit
, the segment will only include hits where a purchase occurred, and no other hits. This could be useful in seeing which products were most popular.
In the above example, the context for the container listed is hits
. This means that the container will only evaluate data at the hit level, (in contrast to visit or visitor level). The rows it will contain will also be at the hit level.
Row
A row is a single record inside of a container. The information stored in a row depends on the context setting for the container. For example, if the context is set to visitor
, the row in the container will contain all information about the visitor spanning all hits from all visits. To contrast, if the context is set to 'hits', the row will only contain information related to the individual qualifying hits in the segment logic.
In the above example, the container is set to a hit
context. The container’s logic states that it will only include hits that have a page
variable set. Therefore, the container will only store rows of hit records where a page was set.
Container
A container groups the segment logic and context together for use in calculating the rows that will be assigned to the container.
A container has three properties:
-
func
-
context
-
pred
In the above example, the container’s context is set to hits
and a rule that only includes hits where the page
attribute is set.
Container Set
A container set
groups containers and creates cartesian relationships between them using boolean expressions. For example, you may have a container that groups visitors that have a purchase, and a second container that groups visitors who came to the website via a specific banner ad. The container set could link these two containers with an AND condition. The result would be a segment containing visitors who belong in both containers, i.e., visitors who made a purchase who also came to the website via a specific banner ad. It would not include visitors who came to the website via the banner ad who never purchased anything.
In the above example, there is only one container, so no container set is needed.
Data Set
A data set is the collection of all records used across containers and container sets to calculate the population of the segment.
Schema Functions
| Function | Description | Parameters |
|---|---|---|
attr |
References an attribute in the schema. For example, |
|
| Function | Description | Parameters |
|---|---|---|
event |
References an event from the schema. For example, |
|
total |
Sums an event across the context resulting in a value that can be used in comparisons. |
|
event-exists |
Checks for the existence of the event in the context. |
|
not-event-exists |
Checks for the lack of the event in the context. |
|
| Function | Description | Parameters |
|---|---|---|
segment |
Holds the definition of the segment. It is the top level object. |
|
container |
Identifies the context and defines segment logic. |
|
and |
Groups multiple |
|
or |
Groups multiple |
|
without |
Performs a boolean |
|
sequence |
A group of conditions that must occur in the provided order. |
|
sequence-prefix |
A list of conditions that must occur before a certain event. |
|
sequence-suffix |
A list of conditions that must occur after a certain event. |
|
sequence-and |
A group of unordered conditions that must all occur. |
|
sequence-or |
A group of unordered conditions. Any individual condition (or more) must occur. |
|
Available Data Comparison Functions
| Function | Description | Parameters |
|---|---|---|
streq |
Equals |
|
not-streq |
Not Equals |
|
strlt |
Less Than |
|
strgt |
Greater Than |
|
strle |
Less Than or Equals |
|
strge |
Greater Than or Equals |
|
streq-any-of |
Match a string to any of the values in the parameter |
|
not-streq-any-of |
Ensure a string doesn’t match any of the values in the parameter |
|
contains |
Ensure a string matches or contains the value in the parameter |
|
not-contains |
Ensure a string doesn’t match or contains the value in the parameter |
|
contains-any-of |
Ensure a string contains any of the values in the parameter. Case-insensitive. |
|
contains-all-of |
Ensure a string contains all of the values in the parameter. Case-insensitive. |
|
not-contains-any-of |
Ensure a string doesn’t contain at least one of the values in the parameter. Case-insensitive. |
|
not-contains-all-of |
Ensure a string doesn’t contain any of the values in the parameter. Case-insensitive. |
|
starts-with |
Ensure a string starts with the value in the parameter. Case-insensitive. |
|
ends-with |
Ensure a string ends with the value in the parameter. Case-insensitive. |
|
not-starts-with |
Ensure a string doesn’t start with the value in the parameter. Case-insensitive. |
|
not-ends-with |
Ensure a string doesn’t end with the value in the parameter. Case-insensitive. |
|
matches |
Ensure a string matches the glob parameter. A glob parameter uses a '' character to match any sequence of characters. A literal '' is expressed with '\*'. |
|
not-matches |
Ensure a string doesn’t match the glob parameter. A glob parameter uses a '' character to match any sequence of characters. A literal '' is expressed with '\*'. |
|
| Function | Description | Parameters |
|---|---|---|
eq |
Equals |
|
not-eq |
Not equals |
|
gt |
Greater than |
|
lt |
Less than |
|
ge |
Greater than or equal to |
|
le |
Less than |
|
eq-any-of |
Equal to any of the values provided |
|
not-eq-any-of |
Not equal to any of the values provided |
|
| Function | Description | Parameters |
|---|---|---|
exists |
Tests if an attribute has been set to a value. |
|
not-exists |
Tests if an attribute has never been set to a value. |
|
| Function | Description | Parameters |
|---|---|---|
time-restriction |
Used to determine if a checkpoint occurred within a given time frame. |
|
container-restriction |
Used to determine if checkpoints described in other containers have happened in a specific sequence. |
|
dimension-restriction |
Used between checkpoints to specify the activity can exist in sequence between them. |
|
exclude-next-checkpoint |
Ensures the next checkpoint doesn’t happen between the preceding checkpoint and the subsequent checkpoint. If there is no subsequent checkpoint then the excluded checkpoint must not occur at any point after the preceding checkpoint. If there is no preceding checkpoint then the excluded checkpoint must not have occurred at any point preceding the subsequent checkpoint. |
For more details, see the documentation published here: https://experiencecloud.adobe.com/resources/help/en_US/analytics/segment/seg_sequential_build.html
Segment Definition Examples
Example 1
Test if an attribute has been set to any value across all of a visitor’s activity.
{ "func":"segment", "version":[ 1, 0, 0 ], "container": { "func": "container", "context": "visitors", "pred": { "func": "exists", "val": { "func":"attr","name":"variables/page" } } } }
Example 2
Test if an attribute has been set to a specific value across all of a visitor’s activity.
{ "func":"segment", "version":[ 1, 0, 0 ], "container": { "func": "container", "context": "visitors", "pred": { "func": "streq", "val": { "func":"attr","name":"variables/page" }, "str": "Main Landing Page" } } }
Example 3
Test if an attribute has been set to a specific value, and then set to a different value.
{ "func":"segment", "version":[ 1, 0, 0 ], "container": { "func": "container", "context": "visitors", "pred": { "func": "sequence", "stream": [ { "func":"container", "context":"hits", "pred": { "func": "streq", "str": "Main Landing Page", "val": { "func":"attr", "name":"variables/page" } } }, { "func":"container", "context":"hits", "pred": { "func": "streq", "str": "Product Search", "val": { "func":"attr", "name":"variables/page" } } } ] } } }
Example 4
Test that both an attribute has been set to any value, and a different attribute has been set to a specific value.
{ "func":"segment", "version":[ 1, 0, 0 ], "container": { "func": "container", "context": "visitors", "pred": { "func": "and", "preds": [ { "func":"container", "context":"hits", "pred": { "func": "exists", "val": { "func":"attr", "name":"variables/page" } } }, { "func":"container", "context":"hits", "pred": { "func": "streq", "str": "Main Landing Page", "val": { "func":"attr", "name":"variables/page" } } } ] } } }
Example 5
Test that both an attribute has been set to any value, and a different attribute has been set to a specific value within the same month.
{ "func":"segment", "version":[ 1, 0, 0 ], "container": { "func": "container", "context": "visitors", "pred": { "func": "sequence", "stream": [ { "func":"container", "context":"hits", "pred": { "func": "streq", "str": "Main Landing Page", "val": { "func":"attr", "name":"variables/page" } } }, { "func":"time-restriction", "count":"1", "limit":"within", "unit":"month" }, { "func":"container", "context":"hits", "pred": { "func": "streq", "str": "Product Search", "val": { "func":"attr", "name":"variables/page" } } } ] } } }
Migrating to the New API
This guide is intended to help users of the 1.3/1.4 versions of the Analytics API migrate to the newer and more capable /ranked
API.
If you’ve used the Analytics APIs in the past, you’ll find some commonalities with that API, but will also notice some stark differences. The biggest difference you’ll notice is that breakdowns aren’t automatically requested for you. Requests need to be chained together retrieve breakdown data.
The /ranked
endpoint utilizes the same underlying processing pipeline as the Analysis Workspace UI. Gone are the days of seeing different numbers in the API and the UI.
Unifying the processing back-ends also ensures that as features are released in the UI, they will become available quickly within the API as well.
Finally, the /ranked
endpoint is a simple REST GET call and no longer requires a queue/get workflow to retrieve data. This will greatly simplify development and maintenance of API clients.
Use Case Differences
The /ranked
end point is intended to quickly run very small requests. To contrast, the 1.3/1.4 APIs could handle requests that required 1-2 days to run!
Requests of this nature usually use a small granularity like hour
or day
, request a large time frame, request lots of metrics at once, and request many breakdowns. To make it worse, sometimes they include classifications as well. All of these features stack up to make reports run very slowly.
To migrate to the /ranked
end point, these large requests will need to be broken down into many smaller requests. The results will then need to be stitched together.
For example, consider the following 1.4 request:
{ "reportDescription": { "reportSuiteID":"mainglobalprod", "dateFrom":"2015-01-01", "dateTo":"2017-12-31", "granularity":"day", "metrics": [ {"id":"pageviews"}, {"id":"visits"}, {"id":"revenue"}, {"id":"orders"}, {"id":"visits"}, ], "elements": [ {"id":"trackingCode", "top":10}, {"id":"geocity", "top":100}, {"id":"page","top":100} ] } }
This report will query ten campaign items. For each of those, it will query one hundred geocity items. Finally, for each city, it will query the top 100 products. This report has the potential to return 10,000,000 records. In addition, it will try to get five metrics for each of those items! Finally, it will try to do that for each day going back a few years.
When making requests to the /ranked
endpoint, smaller requests are better. The above example could be reduced into the following requests that can be made in parallel:
-
Request the top ten
trackingCode
values for the given time period. -
For each of the values returned, request a breakdown of the top 100
geocity
values -
For each of those values, request a breakdown of the top 100
page
values -
Finally, a separate report for each metric. This means you go through steps 1-4 for
pageviews
, then again forvisits
, and so on.
One could also make the argument that historical data could be cached as part of the client application. This means that every day, only the newest day’s worth of data would need to be requested.
Breakdowns
One of the advantages of using the /ranked
end point is the ability to request as many breakdowns as you’d like. To contrast, the 1.4 API was limited to four.
To request a breakdown report, you’ll want to use an itemId
in the metricFilter
section of your request. Refer to the 'Breakdown requests' section of the 'Ranked Endpoint User Guide' for more information.
Metric and Dimension Names
Metric and dimension names have changed slightly. Use the GET /metrics
and /dimensions
endpoints to retrieve a full list of available metrics and dimensions for your report suite.
Real-time and Current Data
The "source"="realtime"
and "currentData"=true
flags in the 1.4 API allow a client to request data that is minutes (possibly seconds) old. The /ranked
endpoint doesn’t currently support this functionality. It is currently recommended that use cases that require real-time data continue to use the 1.4 API or LiveStream.
Classifications User Guide
Overview
The Classifications API provides access to management tools that administer classifications settings within a login company. For more information about what classifications are and how they can be useful, please see the implementation guide.
Definitions
-
column
- A list of values that map to a key. For example, if grouping product skus by category, acolumn
would provide a mapping between the sku and category. -
subscription
- Associates a dimension/report suite to aclassification set
. This allows a user to upload classification data once and have it apply to multiple dimensions across multiple report suites. -
classification set
- A collection ofsubscription
records containing classification columns. -
job
- When classifications tasks are performed, ajob
is created to document the task and provide status. -
artifact
- An object that contains classification data. Usually accessed via an artifact id.
Creating a Classification
Two steps are required when creating a classification. A classification set
must be created in order to define the classification and associate it with the correct dimensions and report suites. Once created, classification data must be imported.
Create a Classification Set
The POST /classifications/dataset/
endpoint can be used to create a new classification set and will return a new classificationSetId
. This call will also create a subscription
and column
record.
$ curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d '{"name":"Product Categories","description":"Groups product SKUs together into categories.","columns":[{"name":"col1","displayName":"Category"}],"subscriptions":[{"rsid":"[RSID]","dimension":"variables/product"}]}' "[analytics_services_base_url]/classifications/dataset/"
This will do three things:
-
Create a
classification set
-
Create a
column
and link it to theclassification set
-
Create a
subscription
that associates this column to a dimension and report suite and links it to theclassification set
The subscription
is what indicates to the classification system which dimensions and report suites to apply the classification to.
|
Note
|
If you use the |
Import Data
Data can be imported two ways - via the API or via a batch upload. This guide will cover the API import.
Let’s use the following classification data as an example:
key,col1 sku1,Category 1 sku2,Category 1 sku3,Category 2 sku4,Category 3 sku5,Category 3 sku6,Category 2 sku7,Category 1
When constructing our request, there are a few things to keep in mind:
* A trailing new line in the import payload will cause the import to fail.
* Because this data is formatted using commas, the dataFormat
parameter should be set to csv
.
* Notifications can be sent when the job changes state. For that reason, we’ll configure the job to notify<EMAIL_ADDRESS>.
* The import payload must be base64 encoded and set to the dataUri
parameter.
* The dataUri
parameter requires a preamble that indicates how the data is formatted. Since we’re using csv
, the preamble will be data:text/csv;base64,
.
|
Note
|
We’re using the |
$ curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d '{"dataFormat":"csv","encoding":"utf8","jobName":"Import Category Information","notifications":[{"method":"email","recipients":["noreply@adobe.com"]}],"dataUri":"data:text/csv;base64,a2V5LGNvbDENCnNrdTEsQ2F0ZWdvcnkgMQ0Kc2t1MixDYXRlZ29yeSAxDQpza3UzLENhdGVnb3J5IDINCnNrdTQsQ2F0ZWdvcnkgMw0Kc2t1NSxDYXRlZ29yeSAzDQpza3U2LENhdGVnb3J5IDINCnNrdTcsQ2F0ZWdvcnkgMQ=="}' "[analytics_services_base_url]/classifications/dataset/[DATASETID]/import"
Checking Import Status
Instead of waiting for notifications, the status of a job can be queried:
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/jobs/[JOBID]"
This API can be used to check the status of an export request as well if data is being exported to an FTP site.
A job has several states:
-
created - The request has been captured
-
queued - The request has been added to the job queue for validation
-
validated - The request has been successfully validated and will await processing
-
failed_validation - The job has failed as a result of failed validation
-
processing - The job is currently being processed
-
failed_processing - The job has failed processing
-
completed - The job has been completed
Getting Classification Data
The API also allows a client to retrieve all information about the current classification configuration.
Get Current Classification Sets
You can use the API to get the current classification set
, column
and subscription
information.
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/dataset"
Or, to get a specific classification set
:
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/dataset/[DATASETID]"
Export Data
The export workflow has a few steps:
-
Create an Export Job
-
Check the Status
-
Fetch the Artifact ID
-
Request the Data
Create an Export Job
$ curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d '{"dataFormat":"csv","encoding":"latin1","jobName":"Export Category Data"}' "[analytics_services_base_url]/classifications/dataset/[DATASETID]/export"
This will create an export job. This can take quite a while to complete if the requested data is large. Use filters in the request body to limit the data that comes back.
Fetch the Status
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/jobs/[JOBID]"
This will provide information about the status of the export job. When the returned status is completed
you can call the artifact endpoint to retrieve an artifact ID.
Fetch the Artifact ID
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/jobs/[JOBID]/artifact"
This will return an artifact object containing the artifact ID. The artifact ID will be a string that represents a file in the classifications system. This ID will be used to retrieve the data.
Request the Data
$ curl --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" "[analytics_services_base_url]/classifications/jobs/[JOBID]/artifact/[ARTIFACTID]"
The response will be the requested classification data. If the data format provided when the job was created was 'json', the data will be streamed in a JSON streaming format.
|
Note
|
More information about JSON Streaming is available here. Most JSON parsers will throw an exception if the entire response payload is decoded. Instead, provide, one line at a time to the parser. |
Unclassified Values
Migrating From Saint
The new classifications system makes some fundamental changes to the way classifications are handled.
-
The new Job API provides current status on import and export jobs
-
Campaign dates are gone
-
Numeric and date classifications are gone
-
A
classification set
can be used to apply a single classification to multiple dimensions across multiple report suites. This makes managing classifications much easier. -
Bulk APIs for managing classification data are available
-
Imported classifications are applied within minutes vs. days
Resources
The following section is a list of the API end-points or Resources available in Adobe Analytics Services.
Approvals
Operations on approvals
Marks an item as approved
POST /approvals
Description
Takes an array of components and marks them all as "Approved"
Body parameter
Array containing a list of Component objects to be marked as "Approved"
Name : body
Flags : optional
Type : < Approval > array
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation; only admins can approve components |
No Content |
500 |
Internal Server Error; unable to create approvals for the specified components |
No Content |
Consumes
-
application/json
Produces
-
application/json
Returns a list of approval objects for the current user. Response is paged based on the provided paging criteria.
GET /approvals
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
limit |
Number of results per page |
integer |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
userid |
The user ID to return details for. Only admins may use this query parameter. |
integer (int32) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Approval > array |
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation |
No Content |
500 |
Internal Server Error; unable to retrieve approvals |
No Content |
Produces
-
application/json
Un-approve the specified components (delete approvals)
DELETE /approvals
Description
Only Admins can create and delete approvals.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
componentIds |
Comma-delimited list of componentIds for which to remove approvals |
string |
Query |
componentType |
Type of component |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< < string, object > map > array |
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation; only admins can un-approve a segment |
No Content |
500 |
Internal Server Error; unable to delete approvals for the specified components |
No Content |
Produces
-
application/json
Retrieves an approval object by its id
GET /approvals/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The approval ID to be returned |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
403 |
Insufficient access to perform operation |
No Content |
404 |
The specified approvalId could not be found |
No Content |
500 |
Internal Server Error; unable to retrieve the specified approval |
No Content |
Produces
-
application/json
Deletes the approval with the given id
DELETE /approvals/{id}
Description
Only admins can create and delete approvals
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The approval ID to be deleted |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< string, object > map |
403 |
Insufficient access to perform operation; user does not have access to delete the approval. |
No Content |
404 |
The specified approval does not exist |
No Content |
500 |
Internal Server Error; unable to delete the specified approval |
No Content |
Produces
-
application/json
Calculatedmetrics
Create a new Calculated Metric
POST /calculatedmetrics
Description
Creates a new calculated metric. The following attributes are available when creating a calculated metric:
|
Important
|
Required Fields: name, definition, rsid |
Optional fields: description
Example definition for use in testing API below ("Page exists"):
{"definition":{},"version":[1,0,0]}
A calculated metric response will always include these default items:* id, name, description, rsid, owner*
Other attributes can be optionally requested through the 'expansion' field as defined/documented in the GET endpoints (see GET "/calculatedmetrics" or GET "/calculatedmetrics/{id}" for more documentation).
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional calculated metric metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, isDeleted, approved, favorite, shares, tags, sharesFullName, usageSummary, usageSummaryWithRelevancyScore, definition, authorization, compatibility, warning) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Body parameter
JSON-formatted Object containing key/value pairs for calculated metric creation.
Name : body
Flags : optional
Type : AnalyticsCalculatedMetric
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object. |
|
500 |
External API error; Calculated metric create or retrieval failed |
Consumes
-
application/json
Produces
-
application/json
Example
The following example creates a new calculated metric called Average Visits per Visitor by dividing metrics visits
by visitors
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d "{ \"name\": \"Average Visits per Visitor\", \"description\": \"Visits divided by Visitors\", \"rsid\": \"sistr2\", \"owner\": { \"id\": 82365 }, \"polarity\": \"positive\", \"precision\": 0, \"type\": \"decimal\", \"definition\": { \"formula\": { \"col1\": { \"name\": \"metrics/visits\", \"func\": \"metric\" }, \"col2\": { \"name\": \"metrics/visitors\", \"func\": \"metric\" }, \"func\": \"divide\" }, \"func\": \"calc-metric\", \"version\": [1,0,0] } }" "https://mc.adobe.io/mc/analytics/reporting/calculatedmetrics?locale=en_US"
The following is an example that creates a new calculated metric that divides visits
by visitors
and then adds page views
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer [ACCESSTOKEN]" -d "{ \"name\": \"Average Visits per Visitor plus Page Views\", \"description\": \"Visits divided by Visitors plus Page Views\", \"rsid\": \"sistr2\", \"owner\": { \"id\": 82365 }, \"polarity\": \"positive\", \"precision\": 0, \"type\": \"decimal\", \"definition\": { \"func\": \"calc-metric\", \"formula\": { \"func\": \"add\", \"col1\": { \"func\": \"divide\", \"col1\": { \"func\": \"metric\", \"name\": \"metrics/visits\" }, \"col2\": { \"func\": \"metric\", \"name\": \"metrics/visitors\" } }, \"col2\": { \"func\": \"metric\", \"name\": \"metrics/pageviews\" } }, \"version\": [1,0,0] } }" "{analytics_services_base_url}/calculatedmetrics?locale=en_US"
Retrieve many calculated metrics
GET /calculatedmetrics
Description
A calculated metric response will always include these default items: id, name, description, rsid, owner
Other attributes can be optionally requested through the 'expansion' field:
-
modified: Date that the metric was last modified (ISO 8601)
-
definition: Calculated metric definition as JSON object
-
compatibility: Products that the metric is compatible with
-
reportSuiteName: Also return the friendly Report Suite name for the RSID
-
favorite: True if calculated metric has been marked as a 'Favorite'
-
tags: Gives all existing tags associated with the calculated metric
-
approved: True if calculated metric has been marked as 'Approved'
-
shares: Gives all existing shares for the calculated metric
-
sharesFullName: Give 'shares', but also include the shared-to user’s friendly login name as 'shareToDisplayName' in each share object
-
ownerFullName: Add friendly full login name (string) to the 'owner' object
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
approved |
Filter list to only include calculated metrics that are approved |
boolean |
|
Query |
calculatedMetricFilter |
Filter list to only include calculated metrics in the specified list (comma-delimited list of IDs) |
string |
|
Query |
expansion |
Comma-delimited list of additional calculated metric metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, isDeleted, approved, favorite, shares, tags, sharesFullName, usageSummary, usageSummaryWithRelevancyScore, definition, authorization, compatibility, warning) > array(multi) |
|
Query |
favorite |
Filter list to only include calculated metrics that are favorites |
boolean |
|
Query |
filterByIds |
Filter list to only include calculated metrics in the specified list (comma-delimited list of IDs) (this is the same as calculatedMetricFilter, and is overwritten by calculatedMetricFilter |
string |
|
Query |
filterByModifiedAfter |
Filter list to only include calculated metrics modified since this date (ISO8601 format) |
string |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
locale |
Locale |
string |
|
Query |
name |
Filter list to only include calculated metrics that contains the Name |
string |
|
Query |
ownerId |
Filter list to only include calculated metrics owned by the specified loginId |
integer (int32) |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
pagination |
return paginated results |
enum (true, false) |
|
Query |
rsids |
Filter list to only include calculated metrics tied to specified RSID list (comma-delimited) |
string |
|
Query |
tagNames |
Filter list to only include calculated metrics that contains one of the tags |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< AnalyticsCalculatedMetric > array |
400 |
Unable to retrieve list of calculated metrics shared with user |
|
401 |
Owner filter error; user specified is not in the same company as the requesting user |
|
403 |
Requesting non-shared calculated metrics for other users is restricted to admin users |
|
500 |
External API error; Calculated metric retrieval failed |
Produces
-
application/json
Retrieve calculated metric functions
GET /calculatedmetrics/functions
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< CalcMetricFunction > array |
500 |
External API error; Calculated metric functions retrieval failed |
Produces
-
application/json
Retrieve a calculated metric function by id
GET /calculatedmetrics/functions/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The function ID to retrieve |
string |
|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
404 |
Calculated metric function not found |
|
500 |
External API error; Calculated metric function retrieval failed |
Produces
-
application/json
Retrieve a single calculated metric by id
GET /calculatedmetrics/{id}
Description
A calculated metric response will always include these default items: id, name, description, rsid, owner
Other attributes can be optionally requested through the 'expansion' field:
-
modified: Date that the metric was last modified (ISO 8601)
-
definition: Calculated metric definition as JSON object
-
compatibility: Products that the metric is compatible with
-
reportSuiteName: Also return the friendly Report Suite name for the RSID
-
favorite: True if calculated metric has been marked as a 'Favorite'
-
tags: Gives all existing tags associated with the calculated metric
-
approved: True if calculated metric has been marked as 'Approved'
-
shares: Gives all existing shares for the calculated metric
-
sharesFullName: Give 'shares', but also include the shared-to user’s friendly login name as 'shareToDisplayName' in each share object
-
ownerFullName: Add friendly full login name (string) to the 'owner' object
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The calculated metric ID to retrieve |
string |
|
Query |
expansion |
Comma-delimited list of additional calculated metric metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, isDeleted, approved, favorite, shares, tags, sharesFullName, usageSummary, usageSummaryWithRelevancyScore, definition, authorization, compatibility, warning) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
403 |
Requesting non-shared calculated metrics for other users is restricted to admin users |
|
500 |
External API error; calculated metric retrieval failed |
Produces
-
application/json
Update an existing calculated metric
PUT /calculatedmetrics/{id}
Description
The following fields can be modified through this endpoint: <br><b>name, description, definition, owner, rsid</b>Example "defintion" for use in testing API below ("Page exists"):<br>"definition":{},"version":[1,0,0]}<br><br>Response will be the newly modified calculated metric object after the update request completes.<br><br><b><span style="text-decoration: underline;">CalculatedMetricResponse</span></b><br>A calculated metric response will always include these default items:* id, name, description, rsid, owner*
Other attributes can be optionally requested through the 'expansion' field as defined/documented in the GET endpoints (see GET "/calculatedmetrics" or GET "/calculatedmetrics/{id}" for more documentation).
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
Calculated Metric ID to be updated |
string |
|
Query |
expansion |
Comma-delimited list of additional calculated metric metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, isDeleted, approved, favorite, shares, tags, sharesFullName, usageSummary, usageSummaryWithRelevancyScore, definition, authorization, compatibility, warning) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Body parameter
JSON-formatted Object containing key/value pairs to be updated.
Name : body
Flags : optional
Type : AnalyticsCalculatedMetric
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Definition must be formatted as a JSON Object |
|
401 |
Company mismatch; calculated metric ownership can only be transferred within the same organization |
|
403 |
User does not have permission to update this calculated metric |
|
500 |
External API error; Calculated metric update or retrieval failed |
Consumes
-
application/json
Produces
-
application/json
Deletion of Calculated Metrics by Id
DELETE /calculatedmetrics/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The calculated metric ID to be deleted |
string |
|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
External API error; Calculated metric delete failed |
Produces
-
application/json
Classifications
Creates a classification set.
POST /classifications/dataset
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Retrieves all classification sets.
GET /classifications/dataset
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
limit |
Documents per page |
integer (int32) |
Query |
page |
Page |
integer (int32) |
Query |
sortField |
Sort field |
enum (name, modified, created) |
Query |
sortOrder |
Sort order |
enum (asc, desc) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< ClassificationSet > array |
Produces
-
application/json
Retrieves classification sets based on search criteria.
POST /classifications/dataset/search
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
limit |
Documents per page |
integer (int32) |
Query |
page |
Page |
integer (int32) |
Query |
sortField |
Sort field |
enum (name, modified, created) |
Query |
sortOrder |
Sort order |
enum (asc, desc) |
Body parameter
JSON-formatted Object containing key/value pairs for search.
Name : body
Flags : optional
Type : ClassificationSetFilterArgs
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< ClassificationSet > array |
Produces
-
application/json
Retrieves a single classification set.
GET /classifications/dataset/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id for which to retrieve information |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Updates a classification set.
PUT /classifications/dataset/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id for the classification set to update |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Deletes a classification set.
DELETE /classifications/dataset/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id for the classification set to delete |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Creates an export job for a classification set.
POST /classifications/dataset/{id}/export
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id for the classification set for which to import data |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Retrieves classification jobs.
GET /classifications/jobs
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
datasetId |
ClassificationSetId filter |
string |
Query |
limit |
Documents per page (minimum limit is 10) |
integer (int32) |
Query |
page |
Page |
integer (int32) |
Query |
sortField |
Sort field |
enum (type, name) |
Query |
sortOrder |
Sort order |
enum (asc, desc) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< ClassificationJob > array |
Produces
-
application/json
Retrieves a single classification job.
GET /classifications/jobs/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The job id for which to retrieve information |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Retrieves info about the first artifact for a given job id.
GET /classifications/jobs/{id}/artifact
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The job id for which to retrieve information |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Retrieves the artifact for a given job and artifact id.
GET /classifications/jobs/{id}/artifact/{artifactId}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
artifactId |
The artifact id for which to retrieve information |
string |
Path |
id |
The job id for which to retrieve information |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
default |
successful operation |
No Content |
Runs an oberon report to get unclassifed values for the given classification set.
GET /classifications/unclassified/{classificationSetId}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
classificationSetId |
The id for which to retrieve information |
string |
|
Query |
allowRemoteLoad |
Controls if Oberon should remote load data. Default behavior is true with fallback to false if remote data does not exist |
enum (true, false, default) |
|
Query |
dateRange |
Format: YYYY-MM-DD/YYYY-MM-DD |
string |
|
Query |
dimension |
Dimension to run the report against |
string |
|
Query |
endDate |
Format: YYYY-MM-DD |
string |
|
Query |
includeOberonXml |
Controls if Oberon XML should be returned in the response - DEBUG ONLY |
enum (true, false) |
|
Query |
rsid |
RSID to run the report against |
string |
|
Query |
startDate |
Format: YYYY-MM-DD |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Collections
Analytics Collections
Retrieves report suites that match the given filters.
GET /collections/suites
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional metadata fields to include on response. |
< enum (name, parentRsid, numGroups, currency, calendarType, currentTimezoneOffset, timezoneZoneinfo) > array(multi) |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
rsidContains |
Filter list to only include suites whose rsid contains rsidContains. |
string |
|
Query |
rsids |
Filter list to only include suites in this RSID list (comma-delimited) |
string |
|
Query |
userGroupId |
Filter list to only include suites that are in the given userGroupId |
integer (int32) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; report suite retrieval failed |
No Content |
Produces
-
application/json
Retrieves report suite by id
GET /collections/suites/{rsid}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
rsid |
The rsid of the suite to return |
string |
Query |
expansion |
Comma-delimited list of additional metadata fields to include on response. |
< enum (name, parentRsid, numGroups, currency, calendarType, currentTimezoneOffset, timezoneZoneinfo) > array(multi) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; report suite retrieval failed |
No Content |
Produces
-
application/json
Companies
Analytics Company Service
Retrieves information about the login company for the current user.
GET /companies/me
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
expansion |
Comma-delimited list of company expansions. |
< enum (validEmails, allowAdobeEmails, companySecurity, billingTabAccess) > array(multi) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; company retrieval failed |
No Content |
Produces
-
application/json
Retrieves the tracking server for the login company of the current user.
GET /companies/me/trackingserver
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
rsid |
The rsid to use if this company does not require namespace use. |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; tracking server retrieval failed |
No Content |
Produces
-
application/json
Dimensions
Dimensions service
Returns a list of dimensions for a given report suite.
GET /dimensions
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
classifiable |
Only include classifiable dimensions. |
enum (true) |
|
Query |
dataGovernanceLabels |
Filter the response based on data governance labels. Search for multiple lables using a comma-delimited string format. Any metric/dimension containing one or more of the provided labels will be returned. |
< string > array(multi) |
|
Query |
dataGovernanceNamespaces |
Filter the response based on data governance namespaces. Search for multiple namespaces using a comma-delimited string format. Any dimension containing one or more of the provided namespaces will be returned. |
< string > array(multi) |
|
Query |
expansion |
Add extra metadata to items (comma-delimited list) |
< enum (tags, approved, favorite, usageSummary, attributes) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Query |
reportTimeAttribution |
Only include dimensions that support reportTimeAttribution. |
enum (true) |
|
Query |
reportable |
Only include dimensions that are valid within a report. |
enum (true) |
|
Query |
rsid |
A Report Suite ID |
string |
|
Query |
segmentable |
Only include dimensions that are valid within a segment. |
enum (true) |
|
Query |
support |
Comma-delimited list of products to filter the dimension list by. Possible values are 'oberon' and 'dataWarehouse'. |
< enum (oberon, dataWarehouse) > array(multi) |
|
Query |
supportsDataGovernance |
Only include dimensions that contain dataGovernance attribute. |
enum (true) |
|
Query |
useCache |
Enable caching for faster requests. |
boolean |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< AnalyticsDimension > array |
400 |
Invalid JSON input |
No Content |
401 |
User does not have access to this report suite |
No Content |
500 |
Unexpected internal server error |
No Content |
Produces
-
application/json
Example
The following example gets dimensions for the provided report suite.
Example Curl Request
curl -X GET --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/dimensions/?rsid={report_suite}"
Get all gdpr namespaces for a user’s ims org
GET /dimensions/datagovernance/namespaces
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
useCache |
Enable caching |
boolean |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
Success status |
< string > array |
Produces
-
application/json
Returns the names of the dimension items listed in the post body.
POST /dimensions/values
Description
Given a dimension name and an itemId, this endpoint returns the text value for that itemId
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
dateRange |
Optionally supply the date range for filtering dimension values (default is last 90 days). Example format: 2014-06-01/2014-06-30 (gives June 2014) |
string |
|
Query |
locale |
Locale to use when returning dimension information. |
string |
|
Query |
rsid |
The report suite ID |
string |
Body parameter
Array of dimensionItem objects where each element contains key-value pairs for "dimension" and "itemId"
Name : body
Flags : required
Type : < DimensionItem > array
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< DimensionItem > array |
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation |
No Content |
500 |
Unexpected internal server error |
No Content |
Produces
-
application/json
Example
The following example gets dimension item names for the provided report suite, dimensions, and itemIds.
Example Curl Request
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" --header "Authorization: Bearer {access_token}" -d "[{\"dimension\":\"variables/operatingsystem\",\"itemId\":\"1\"}]" "{analytics_services_base_url}/dimensions/values?rsid={report_suite}"
Returns a dimension for the given report suite
GET /dimensions/{dimensionId}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
dimensionId |
The dimension ID. For example a valid id is a value like 'evar1' |
string |
|
Query |
expansion |
Add extra metadata to items (comma-delimited list) |
< enum (tags, approved, favorite, usageSummary, attributes) > array(multi) |
|
Query |
locale |
The locale to use for returning system named dimensions. |
string |
|
Query |
rsid |
The report suite ID. |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
401 |
User Doesn’t have sufficient privileges |
No Content |
Produces
-
application/json
Example
The following example gets current settings for the
dimension for the provided report suite.evar1
Example Curl Request
curl -X GET --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/dimensions/evar1?rsid={report_suite}"
Favorites
Operations on managing favorites on components
Creates 'favorite' records for a given component
POST /favorites
Description
Accepts an array of Favorite objects to allow creation of one or many 'favorite' records in a single call.
Body parameter
JSON-formatted ARRAY containing a list of favorite objects
Name : body
Flags : required
Type : < Favorite > array
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Consumes
-
application/json
Produces
-
application/json
Example
The following example gets a single favorite record. If saving a new favorite, all you need is the component ID. If updating an existing favorite, include the favoriteId being updated as a parameter in the POST data.
Example Curl Request - Save New Favorite
curl -X POST --header "Accept: application/json" --header "Content-Type: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites/" -d "[{\"componentId\":\"s300006369_5a5933d21d43f6274e198fc6\",\"componentType\":\"segment\"}]"
Example Curl Request - Update Existing Favorite
curl -X POST --header "Accept: application/json" --header "Content-Type: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites/" -d "[{\"favoriteId\":\"432933",\"componentId\":\"s300006369_5a5933d21d43f6274e198fc6\",\"componentType\":\"segment\"}]"
Returns a list of favorite objects for the current user meeting the paging restriction
GET /favorites
Description
Returns an array of all of the favorites objects tied to the company. Setting a very large page size will return the list in a single request, but it may be more data than you expect and you may experience performance issues.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
componentIds |
Comma-delimited list of componentIds to filter on. Must also pass componentType. |
string |
|
Query |
componentType |
The component type to filter on. Required if also using componentIds filter. |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
userid |
The user ID to return details for. Only admins may use this option. |
integer (int32) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Favorite > array |
Produces
-
application/json
Example
The following example gets favorite information for the current user.
Example Curl Request
curl -X GET --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites/"
Deletes favorites by componentId. Accepts a list of componentIds and deletes any "Favorites" associated with them
DELETE /favorites
Description
Deletes favorites based on componentIds.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
componentIds |
A comma separated list of component Ids |
string |
Query |
componentType |
The component type to operate on. |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< < string, object > map > array |
Produces
-
application/json
Example
The following example deletes multiple favorite records of the same component type.
Example Curl Request
curl -X DELETE --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites?componentType=bookmark&componentIds=23281257,23281381"
Retrieve a 'favorite' record by id
GET /favorites/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id of the "Favorite" record to return |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Example
The following example gets a single favorite record.
Example Curl Request
curl -X GET --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites/429089"
Deletes the "Favorite" with the given id
DELETE /favorites/{id}
Description
Deletes by favoriteId.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The id of the favorite |
integer (int64) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< string, object > map |
400 |
Attempting to remove a favorite by id that does not exist |
No Content |
403 |
Attempting to remove a favorite for a user other than the authenticated user |
No Content |
Produces
-
application/json
Example
The following example deletes a favorite record.
Example Curl Request
curl -X DELETE --header "Accept: application/json" --header "Authorization: Bearer {access_token}" "{analytics_services_base_url}/favorites/429089"
Metrics
Retrieves a List of Metrics for the Given Report Suite
Returns a list of metrics for the given report suite
GET /metrics
Description
This returns the metrics list primarily for the Analytics product. The platform identity API Returns a list of all possible metrics for the supported systems.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Add extra metadata to items (comma-delimited list) |
< enum (tags, approved, favorite, usageSummary, attributes) > array(multi) |
|
Query |
locale |
Locale that system named metrics should be returned in |
string |
|
Query |
rsid |
ID of desired report suite ie. sistr2 |
string |
|
Query |
segmentable |
Filter the metrics by if they are valid in a segment. |
boolean |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation |
No Content |
500 |
Unexpected internal server error |
No Content |
Produces
-
application/json
Returns a metric for the given report suite
GET /metrics/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The id of the metric for which to retrieve info. Note ids are values like pageviews, not metrics/pageviews |
string |
|
Query |
expansion |
Add extra metadata to items (comma-delimited list) |
< enum (tags, approved, favorite, usageSummary, attributes) > array(multi) |
|
Query |
includeHidden |
Whether to include variables that are hidden in the UI or that the user doesn’t have permission to. |
boolean |
|
Query |
locale |
Locale that system named metrics should be returned in |
string |
|
Query |
rsid |
ID of desired report suite ie. sistr2 |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid JSON input |
No Content |
403 |
Insufficient access to perform operation |
No Content |
500 |
Unexpected internal server error |
No Content |
Produces
-
application/json
Reports
Ranked reports service
Runs a report for the request in the post body
POST /reports
Description
See the Reporting Interface wiki page for details.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
allowRemoteLoad |
Controls if Oberon should remote load data. Default behavior is true with fallback to false if remote data does not exist |
enum (true, false, default) |
|
Query |
includeOberonXml |
Controls if Oberon XML should be returned in the response - DEBUG ONLY |
enum (true, false) |
|
Query |
includePlatformPredictiveObjects |
Controls if platform Predictive Objects should be returned in the response. Only available when using Anomaly Detection or Forecasting- DEBUG ONLY |
enum (true, false) |
|
Query |
useCache |
Use caching for faster requests (Use cached dimensions to speed up permission checks - This does not do any report caching) |
boolean |
|
Query |
usesCatalogIdentities |
Whether this ranked request uses Catalog identities (true) or usual Analytics identities (false). Uses server default (host specific) when not passed. |
boolean |
Body parameter
Name : body
Flags : optional
Type : RankedRequest
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object. |
Consumes
-
application/json
Produces
-
application/json
Runs a ranked report for the report in the post body
POST /reports/ranked
Description
See the Reporting Interface wiki page for details.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
allowRemoteLoad |
Controls if Oberon should remote load data. Default behavior is true with fallback to false if remote data does not exist |
enum (true, false, default) |
|
Query |
includeOberonXml |
Controls if Oberon XML should be returned in the response - DEBUG ONLY |
enum (true, false) |
|
Query |
includePlatformPredictiveObjects |
Controls if platform Predictive Objects should be returned in the response. Only available when using Anomaly Detection or Forecasting- DEBUG ONLY |
enum (true, false) |
|
Query |
useCache |
Use caching for faster requests (Use cached dimensions to speed up permission checks - This does not do any report caching) |
boolean |
|
Query |
usesCatalogIdentities |
Whether this ranked request uses Catalog identities (true) or usual Analytics identities (false). Uses server default (host specific) when not passed. |
boolean |
Body parameter
Name : body
Flags : optional
Type : RankedRequest
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object. |
Consumes
-
application/json
Produces
-
application/json
Returns a segment summary report for the segment definition in the post body
POST /reports/segmentSummary
Description
Requires rsid and definition. Used to validate a segment definition and return basic reporting metrics for that definition.
The response contains products that the definition is compatible with, as well as a series of totals that represent how many Page Views, Visits, and Visitors the segment includes.
Format for the order of Totals in response:
1) Number of Page Views that the segment includes for the given time period
2) Number of Visits that the segment includes for the given time period
3) Number of Unique Visitors that the segment includes for the given time period
4) Total number of Page Views for the time period (non-segmented)
5) Total number of Visits for the time period (non-segmented)
6) Total number of Unique Visitors for the time period (non-segmented)
The overall totals (3-6) can be used with the segment totals (1-3) to determine the percentage of the segment’s audience for each metric.
Example definition for use in testing API below ("Page exists"):
{ "func": "segment", "container": { "func": "container", "context": "hits", "pred": { "func": "exists", "description": "Page", "val": { "func": "attr", "name": "variables/page" } } }, "version": [1, 0, 0] }
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
allowRemoteLoad |
Controls if Oberon should remote load data. Default behavior is true with fallback to false if remote data does not exist |
enum (true, false, default) |
|
Query |
dateRange |
Format: YYYY-MM-DD/YYYY-MM-DD |
string |
|
Query |
endDate |
Format: YYYY-MM-DD |
string |
|
Query |
includeOberonXml |
Controls if Oberon XML should be returned in the response - DEBUG ONLY |
enum (true, false) |
|
Query |
includeVisitorsMcvisid |
Controls if Visitors with Experience Cloud ID should be returned in the response |
enum (true, false) |
|
Query |
locale |
Locale |
string |
|
Query |
rsid |
RSID to run the report against |
string |
|
Query |
startDate |
Format: YYYY-MM-DD |
string |
Body parameter
Segment definition
Name : body
Flags : required
Type : string
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Bad JSON input; request not formatted correctly |
No Content |
403 |
User does not have access to run this report |
No Content |
500 |
Unexpected error; failed to run report |
No Content |
Consumes
-
application/json
Produces
-
application/json
Returns a top items report for the given dimension
GET /reports/topItems
Description
Get the top X items (based on paging restriction) for the specified dimension and rsid. Defaults to last 90 days.
Search Clause examples: contains test: 'test'
contains test or test1: 'test' OR 'test1'
contains test and test1: 'test' AND 'test1'
contains test and not (test1 or test2): 'test' AND NOT ('test1' OR 'test2')
does not contain test: NOT 'test'
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
allowRemoteLoad |
Controls if Oberon should remote load data. Default behavior is true with fallback to false if remote data does not exist |
enum (true, false, default) |
|
Query |
dateRange |
Format: YYYY-MM-DD/YYYY-MM-DD |
string |
|
Query |
dimension |
Dimension to run the report against. Example: "variables/page" |
string |
|
Query |
endDate |
Format: YYYY-MM-DD |
string |
|
Query |
includeOberonXml |
Controls if Oberon XML should be returned in the response - DEBUG ONLY |
enum (true, false) |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
locale |
Locale |
string |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
rsid |
RSID to run the report against |
string |
|
Query |
search-clause |
General search string; wrap with single quotes. Example: 'PageABC' |
string |
|
Query |
searchAnd |
Search terms that will be AND-ed together. Space delimited. |
string |
|
Query |
searchNot |
Search terms that will be treated as NOT including. Space delimited. |
string |
|
Query |
searchOr |
Search terms that will be OR-ed together. Space delimited. |
string |
|
Query |
searchPhrase |
A full search phrase that will be searched for. |
string |
|
Query |
startDate |
Format: YYYY-MM-DD |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
403 |
User does not have access to run this report |
No Content |
500 |
Unexpected error; failed to run report |
No Content |
Produces
-
application/json
Reportsuites
Analytics Report Suite Service
Retrieves report suites that match the given filters.
GET /reportsuites
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional report suite metadata fields to include on response. |
< enum (calendarType, reportSuiteName, baseUrl, defaultPage, currency, calendarAnchorDate, timezone, timezoneZoneinfo) > array(multi) |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
rsidContains |
Filter list to only include suites whose rsid contains rsidContains. |
string |
|
Query |
rsidOrNameContains |
Filter list to only include suites whose rsid or report suite name contains rsidOrNameContains. |
string |
|
Query |
rsids |
Filter list to only include suites in this RSID list (comma-delimited) |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; report suite retrieval failed |
No Content |
Produces
-
application/json
Retrieves calendar type for a single report suite.
GET /reportsuites/{rsid}/calendartype
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
rsid |
rsid |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; retrieval of report suite calendar type failed due to an internal error |
No Content |
Produces
-
application/json
Segments
These operations manage Adobe Analytics Segments. Segments are used to isolate interesting groups of visitors, visits, or hits.
Creates Segment
POST /segments
Description
Creates a segment. See the Segments Endpoint User Guide for more information about using the Segments API. The following attributes are available when creating a segment:
Example "Page exists" segment definition:
{ "name":"Page Exists", "rsid":"adbedocrsid", "description":"This is a segment created by the API.", "definition":{ "func":"segment", "container":{ "func":"container", "context":"hits", "pred":{ "func":"exists", "description":"Page", "val":{ "func":"attr", "name":"variables/page" } } }, "version":[1,0,0] } }
Note: The aamStatus
property is used to publish
a report suite segment to other products in the Experience Cloud. The description
property is always required when publishing with aamStatus
.
The report suite must already be pre-configured for AAM for publishing to succeed (see the AAM Status endpoint for more information).
Format for aamStatus
object:
{ "aamStatus":{ "published":[ "rsid1", "rsid2" ] } }
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional segment metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, approved, favorite, shares, tags, sharesFullName, usageSummary, compatibility, definition) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Body parameter
JSON-formatted Object containing key/value pairs for segment creation.
Name : body
Flags : optional
Type : < string, object > map
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object. |
No Content |
500 |
External API error; Segment create or retrieval failed |
No Content |
Consumes
-
application/json
Produces
-
application/json
SegmentResponse
A segment response will always include these default items:
-
id
The affected segment id -
name
The affected segment’s name -
description
The segment’s description -
rsid
The report suite ID of the associated report suite -
owner
The id of the associated segment owner
Other attributes can be optionally requested through the expansion
field as documented in the GET endpoints Retrieve All Segments and Get a Single Segment.
Example
Let’s create a test segment that only includes hits with a page name.
curl -X POST -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: [TOKEN]" "https://[url]/segments" -d "{\"name\":\"Test Segment\",\"rsid\":\"adbedocrsid\",\"definition\":{\"func\":\"segment\",\"container\":{\"func\":\"container\",\"context\":\"hits\",\"pred\":{\"func\":\"exists\",\"description\":\"Page\",\"val\":{\"func\":\"attr\",\"name\":\"variables/page\"}}},\"version\":[1,0,0]}}"
Retrieve All Segments
GET /segments
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
curatedRsid |
Include the curatedItem status for given report suite ID |
string |
|
Query |
dataGroup |
Filter list to only include segments with the given data group |
string |
|
Query |
dataType |
Filter list to only include segments compatible with the specified product |
enum (dw, oberon) |
|
Query |
expansion |
Comma-delimited list of additional segment metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, approved, favorite, shares, tags, sharesFullName, usageSummary, compatibility, definition) > array(multi) |
|
Query |
filterByIds |
Filter list to only include segments in the specified list (comma-delimited list of IDs) (this is the same as segmentFilter, and is overwritten by segmentFilter |
string |
|
Query |
filterByModifiedAfter |
Filter list to only include segments modified since this date (ISO8601 format) |
string |
|
Query |
includeType |
Include additional segments not owned by user. The "all" option takes precedence over "shared" |
< enum (shared, all, templates, deleted, internal, curatedItem) > array(multi) |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
locale |
Locale |
string |
|
Query |
name |
Filter list to only include segments that contains the Name |
string |
|
Query |
ownerId |
Filter list to only include segments owned by the specified loginId |
integer (int32) |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
pagination |
Return paginated results |
enum (true, false) |
|
Query |
reportTimeAttribution |
Filter list to only include segments by reportTimeAttribution |
boolean |
|
Query |
rsids |
Filter list to only include segments tied to specified RSID list (comma-delimited) |
string |
|
Query |
segmentFilter |
Filter list to only include segments in the specified list (comma-delimited list of IDs) |
string |
|
Query |
tagNames |
Filter list to only include segments that contains one of the tags |
string |
|
Query |
toBeUsedInRsid |
Required when reportTimeAttribution != null or expansion=reportTimeAttribution |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Unable to retrieve list of segments shared with user |
No Content |
401 |
Owner filter error; user specified is not in the same company as the requesting user |
No Content |
403 |
Requesting non-shared segments for other users is restricted to admin users |
No Content |
500 |
External API error; Segment retrieval failed |
No Content |
Produces
-
application/json
AAM Status
GET /segments/aamstatus
Description
Checks the provided report suite to see if it is configured to allow segment sharing with Adobe Audience Manager.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
rsid |
Report suite ID to check status for |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
object |
500 |
External API error; failed to check status for given RSID |
No Content |
Produces
-
application/json
Get a Single Segment
GET /segments/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The segment ID to retrieve |
string |
|
Query |
expansion |
Comma-delimited list of additional segment metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, approved, favorite, shares, tags, sharesFullName, usageSummary, compatibility, definition) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Query |
toBeUsedInRsid |
Evaluate the reportTimeAttribution/customerJourney compatibility for the provided report suite ID |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
403 |
Requesting non-shared segments for other users is restricted to admin users |
No Content |
500 |
External API error; segment retrieval failed |
No Content |
Produces
-
application/json
Update a Segment
PUT /segments/{id}
Updates an existing segment. See the Segments Endpoint User Guide for more information about using the Segments API.
Example "Page exists" segment definition:
{ "name":"Page Exists", "rsid":"adbedocrsid", "description":"This is a segment created by the API.", "definition":{ "func":"segment", "container":{ "func":"container", "context":"hits", "pred":{ "func":"exists", "description":"Page", "val":{ "func":"attr", "name":"variables/page" } } }, "version":[1,0,0] } }
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
Segment ID to be updated |
string |
|
Query |
expansion |
Comma-delimited list of additional segment metadata fields to include on response. |
< enum (reportSuiteName, siteTitle, ownerFullName, modified, approved, favorite, shares, tags, sharesFullName, usageSummary, compatibility, definition) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Body parameter
JSON-formatted Object containing key/value pairs to be updated.
Name : body
Flags : optional
Type : < string, object > map
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Definition must be formatted as a JSON Object |
No Content |
401 |
Company mismatch; segment ownership can only be transferred within the same organization |
No Content |
403 |
User does not have permission to update this segment |
No Content |
500 |
External API error; Segment update or retrieval failed |
No Content |
Consumes
-
application/json
Produces
-
application/json
Example
Let’s update a test segment that only includes hits with a page name.
curl -X PUT -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: [TOKEN]" "https://[url]/segments" -d "{\"name\":\"Test Segment\",\"rsid\":\"adbedocrsid\",\"definition\":{\"func\":\"segment\",\"container\":{\"func\":\"container\",\"context\":\"hits\",\"pred\":{\"func\":\"exists\",\"description\":\"Page Name Exists\",\"val\":{\"func\":\"attr\",\"name\":\"variables/page\"}}},\"version\":[1,0,0]}}"
Delete Segment
DELETE /segments/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The segment ID to be deleted |
string |
|
Query |
locale |
Locale |
string |
|
Query |
version |
Decides the version of segment service |
enum (old, new) |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
string |
500 |
External API error; Segment delete failed |
No Content |
Produces
-
application/json
Tags
Operations on tags
Saves the given tag(s) for the current user’s company
POST /tags
Description
Allows creation of a new tag and applies that new tag to the passed component
Body parameter
JSON-formatted array of Tag objects containing key-value pairs
Name : body
Flags : optional
Type : < Tag > array
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Tag > array |
500 |
Unable to save list of tags. |
No Content |
Consumes
-
application/json
Produces
-
application/json
Returns a list of tags for the current user’s company
GET /tags
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
limit |
Number of results per page |
integer |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Tag > array |
500 |
Unable to retrieve list of tags for user. |
No Content |
Produces
-
application/json
Disassociates all tags from the given components
DELETE /tags
Description
Removes all tags from the passed componentIds. Note that currently this is done in a single DB query, so there is a single combined response for the entire operation.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
componentIds |
Comma-separated list of componentIds to operate on. |
string |
Query |
componentType |
The component type to operate on. |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< string, object > map |
400 |
Invalid component type. |
No Content |
500 |
Unable to remove tags for given components. |
No Content |
Produces
-
application/json
Retrieves a tags for a given component by componentId and componentType
GET /tags/search
Description
Given a componentId, return all tags associated with that component
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Query |
componentId |
The componentId to operate on. Currently this is just the segmentId. |
string |
Query |
componentType |
The component type to operate on. |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Tag > array |
400 |
Invalid component type. |
No Content |
500 |
Unable to retrieve tags for given component. |
No Content |
Produces
-
application/json
Tag a component with one or many tags at once. WARNING: Authoritative; deletes/overwrites all pre-existing associations
PUT /tags/tagitems
Description
This endpoint allows many tags at once to be created/deleted. Any tags passed to this endpoint will become the only tags for that componentId (all other tags will be removed).
Body parameter
JSON-formatted object containing key-value pairs that conform to the schema
Name : body
Flags : optional
Type : < TaggedComponent > array
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< TaggedComponent > array |
500 |
Unable to save tag list. |
No Content |
Consumes
-
application/json
Produces
-
application/json
Retrieves an tag by its id
GET /tags/{id}
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
Tag ID to be retrieved |
integer (int32) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
404 |
Unable to find a tag with the given ID |
No Content |
500 |
Unexpected server error while trying to retrieve tag |
No Content |
Produces
-
application/json
Removes the tagId and all associations from that tag to any components
DELETE /tags/{id}
Description
Delete by tagId. Will un-tag any/all components that were associated with the passed tagId.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
Path |
id |
The tagId to be deleted |
integer (int32) |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< string, object > map |
404 |
The given tagId does not exist |
No Content |
500 |
Unable to delete the given tagId. |
No Content |
Produces
-
application/json
Timezones
Timezone Operations
Retrieves timezones available to be used in Adobe Analytics.
GET /timezones
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
< Timezone > array |
500 |
Unexpected error; timezone retrieval failed |
No Content |
Produces
-
application/json
Virtualreportsuites
Operations on virtual report suites
Creates a new virtual report suite
POST /virtualreportsuites
Description
Creates a virtual report suite. The following attributes are available when creating a virtual report suite: Required: name, parentRsid
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional virtual report suite metadata fields to include on response. |
< enum (globalCompanyKey, parentRsid, parentRsidName, timezone, timezoneZoneinfo, currentTimezoneOffset, segmentList, description, modified, isDeleted, approved, favorite, tags, ownerFullName, compatibility) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Body parameter
JSON-formatted Object containing key/value pairs for virtual report suite creation.
Name : body
Flags : optional
Type : AnalyticsVirtualReportSuite
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
400 |
Invalid input; name and parentRsid are required. |
No Content |
500 |
External API error; Virtual report suite create or retrieval failed |
No Content |
Consumes
-
application/json
Produces
-
application/json
Example
The following is an example request body to create a virtual report suite:
{ "name": "VRS example", "parentRsid": "example", "segmentList": [ "5543e358300456e42411509e", "536bfce4e4b06d874b0ca4c3" ], "timezone": 7 }
Retrieves virtual report suites accessible to the current user.
GET /virtualreportsuites
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
expansion |
Comma-delimited list of additional virtual report suite metadata fields to include on response. |
< enum (globalCompanyKey, parentRsid, parentRsidName, timezone, timezoneZoneinfo, currentTimezoneOffset, segmentList, description, modified, isDeleted, approved, favorite, tags, ownerFullName, compatibility) > array(multi) |
|
Query |
filterByModifiedAfter |
Filter list to only include virtual report suites modified since this date (ISO8601 format) |
string |
|
Query |
idContains |
Filter list to only include suites whose id contains idContains. |
string |
|
Query |
limit |
Number of results per page |
integer |
|
Query |
locale |
Locale |
string |
|
Query |
page |
Page number (base 0 - first page is "0") |
integer |
|
Query |
rsids |
Filter list to only include suites in this RSID list (comma-delimited) |
string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; virtual report suite retrieval failed |
No Content |
Produces
-
application/json
Retrieves a single virtual report suite by ID.
GET /virtualreportsuites/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The vrsid to retrieve |
string |
|
Query |
expansion |
Comma-delimited list of additional virtual report suite metadata fields to include on response. |
< enum (globalCompanyKey, parentRsid, parentRsidName, timezone, timezoneZoneinfo, currentTimezoneOffset, segmentList, description, modified, isDeleted, approved, favorite, tags, ownerFullName, compatibility) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
Unexpected error; virtual report suite retrieval failed |
No Content |
Produces
-
application/json
Updates configuration for a virtual report suite.
PUT /virtualreportsuites/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The vrsid to update |
string |
|
Query |
expansion |
Comma-delimited list of additional virtual report suite metadata fields to include on response. |
< enum (globalCompanyKey, parentRsid, parentRsidName, timezone, timezoneZoneinfo, currentTimezoneOffset, segmentList, description, modified, isDeleted, approved, favorite, tags, ownerFullName, compatibility) > array(multi) |
|
Query |
locale |
Locale |
string |
|
Body parameter
JSON-formatted Object containing virtual report suite keys/value pairs to be updated.
Name : body
Flags : optional
Type : AnalyticsVirtualReportSuite
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
Produces
-
application/json
Delete a virtual report suite by ID
DELETE /virtualreportsuites/{id}
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Path |
id |
The virtual report suite ID to be deleted |
string |
|
Query |
locale |
Locale |
string |
|
Responses
| HTTP Code | Description | Schema |
|---|---|---|
200 |
successful operation |
|
500 |
External API error; Virtual report suite delete failed |
No Content |
Produces
-
application/json
Definitions
The following is a list of schema definitions for the request and response objects handled by the resource endpoints described above.
AdCloudConfiguration
| Name | Schema |
|---|---|
cidUrlParam |
string |
dataSourcesId |
integer (int32) |
secondaryRel |
integer (int32) |
AlternateVariableNames
| Name | Schema |
|---|---|
baseName |
string |
curatedName |
string |
name |
string |
AnalyticsCalculatedMetric
A CalculatedMetric is a custom metric for which its value is dynamically calculated when it is used in a report. The calculation can be done using simple arithmetics or predefined mathematical and logical functions called Calculated Metric Functions. (For more information on see CalcMetricFunction )
Example:
The following snippet shows a calculated metric object named "Average Page Views per Visit".
{
"name": "Average Page Views per Visit",
"description": "",
"rsid": "jjesquireqc.beta",
"owner": {
"id": 600815
},
"polarity": "positive",
"precision": 0,
"type": "decimal",
"definition": {
"formula": {
"func": "divide",
"col1": {
"func": "metric",
"name": "metrics/pageviews",
"description": "Page Views"
},
"col2": {
"func": "metric",
"name": "metrics/visits",
"description": "Visits"
}
},
"func": "calc-metric",
"version": [1,0,0]
}
}
Notice that formula for the above calculated metric is defined as the "Page Views" divided by the "Visits" to the site, therefore the definition object contains the formula:
"formula": {
"func": "divide",
"col1": {
"func": "metric",
"name": "metrics/pageviews",
"description": "Page Views"
},
"col2": {
"func": "metric",
"name": "metrics/visits",
"description": "Visits"
}
}
To get a list of the functions that you utilize in a formula you can call GET /calculatedmetrics/functions and look at the ids.
| Name | Description | Schema |
|---|---|---|
approved |
boolean |
|
authorization |
||
created |
Calculated metric creation date |
string (date-time) |
definition |
Calculated metric definition object |
|
description |
string |
|
favorite |
boolean |
|
id |
System generated id |
string |
isDeleted |
boolean |
|
modified |
string (date-time) |
|
name |
string |
|
owner |
||
polarity |
Set metric polarity, which indicates whether it’s good or bad if a given metric goes up. Default=positive |
enum (positive, negative) |
precision |
Number of decimal places to include in calculated metric result |
integer (int32) |
reportSuiteName |
The report suite name for which the component was created/updated |
string |
rsid |
The report suite id for which the component was created/updated |
string |
shares |
< Share > array |
|
siteTitle |
string |
|
tags |
< Tag > array |
|
template |
boolean |
|
type |
enum (CURRENCY, TIME, DECIMAL, PERCENT) |
|
usageSummary |
||
warning |
AnalyticsClassificationColumn
| Name | Description | Schema |
|---|---|---|
classifiedBy |
An optional classification dataset id, whose dataset classifies this column’s data. |
string |
displayName |
The display name for this given data column. Mutable. Can be any valid UTF-8 string. |
string |
id |
A UUID that will be generated when a column is created. |
string |
identityName |
string |
|
name |
The name for this given data column. Immutable after column creation. Can be any valid UTF-8 string. |
string |
numericId |
string |
|
tags |
Internal column tags. Used to store info (like div nums) to support taxonomist migration. |
< string > array |
type |
Defaults to 'text'. Immutable after column creation. |
enum (text, integer, float, list[string]) |
AnalyticsCuratedComponent
| Name | Schema |
|---|---|
componentId |
string |
componentType |
string |
curatedName |
string |
AnalyticsDataGovernanceLabels
| Name | Schema |
|---|---|
allowedEmpty |
boolean |
defaultLabels |
< string > array |
editable |
boolean |
labels |
< string > array |
usesDefault |
boolean |
AnalyticsDataGovernanceSettings
| Name | Schema |
|---|---|
auth |
|
gdprAccess |
|
gdprDelete |
|
identifiability |
|
namespace |
string |
sensitivity |
AnalyticsDimension
AnalyticsDimension is an object representing a dimension in Analytics. A Dimension represents qualitative characteristics about your data, usually string values. Dimensions are different from Metrics in that Metrics represent a quantifiable characteristics about your data, as in numeric values. (For more information on Metrics see AnalyticsMetric ).
For example the Pages dimension represents the page names in a site, while the Page Views metric represents how many times has each page been viewed. The following table shows a dimension "Pages" and two metrics for that data: "Page Views" and "Visitors".
| Pages (Dimension) | Page Views (Metric) | Visitors (Metric) |
|---|---|---|
home.html |
1012 |
100 |
company.html |
200 |
60 |
about.html |
122 |
122 |
Example
The following example shows a dimension response in JSON format.
{
"id": "variables/aemassetid",
"title": "Asset ID",
"name": "Asset ID",
"type": "string",
"category": "AEM",
"support": [
"oberon",
"dataWarehouse"
],
"pathable": false,
"segmentable": true,
"reportable": [
"oberon"
],
"dataGroup": "aem"
}
Fields
| Name | Schema |
|---|---|
aliasId |
string |
alternateVariableNames |
|
approved |
boolean |
attributes |
< string > array |
attributionModel |
< string, object > map |
breakdownAttributionModel |
< string, object > map |
category |
string |
curatedItem |
boolean |
customerJourney |
boolean |
dataGovernance |
|
dataGroup |
string |
description |
string |
extraTitleInfo |
string |
favorite |
boolean |
fragRelId |
string |
hidden |
boolean |
id |
string |
isEntryOrExit |
boolean |
name |
string |
noAccess |
boolean |
parent |
string |
pathable |
boolean |
reportTimeAttribution |
boolean |
reportable |
< string > array |
segmentable |
boolean |
shares |
< Share > array |
support |
< string > array |
supportsDataGovernance |
boolean |
tags |
< Tag > array |
title |
string |
type |
enum (STRING, INT, DECIMAL, CURRENCY, PERCENT, TIME, ENUM, ORDERED_ENUM) |
usageSummary |
AnalyticsMcAssociation
| Name | Schema |
|---|---|
createTimestamp |
string (date-time) |
createUser |
string |
createdBySystem |
boolean |
dataCenter |
string |
dataSourceId |
integer (int32) |
imsOrgId |
string |
partnerId |
integer (int32) |
rsid |
string |
updateTimestamp |
string (date-time) |
AnalyticsMcAudiences
| Name | Schema |
|---|---|
enabled |
boolean |
AnalyticsMcClusterConfiguration
| Name | Description | Schema |
|---|---|---|
dataSourceId |
the dpid |
string |
AnalyticsMcEstimatedClusters
| Name | Schema |
|---|---|
coopEnabled |
boolean |
estimatedPeople |
|
mcAssociation |
|
rsid |
string |
AnalyticsMetric
AnalyticsMetric is an object representing a metric in Analytics. Metrics represent quantifiable characteristics about your data, as in numeric values. Metrics are different from Dimensions in that a Dimension represents qualitative characteristics about your data, usually string values. (For more information on Dimensions see AnalyticsDimension ).
For example the Pages dimension represents the page names in a site, while the Page Views metric represents how many times has each page been viewed. The following table shows a dimension "Pages" and two metrics for that data: "Page Views" and "Visitors".
| Pages (Dimension) | Page Views (Metric) | Visitors (Metric) |
|---|---|---|
home.html |
1012 |
100 |
company.html |
200 |
60 |
about.html |
122 |
122 |
| Name | Schema |
|---|---|
aliasId |
string |
allocation |
boolean |
alternateVariableNames |
|
approved |
boolean |
attributes |
< string > array |
calculated |
boolean |
category |
string |
curatedItem |
boolean |
customerJourney |
boolean |
dataCollectionType |
string |
dataGovernance |
|
dataGroup |
string |
description |
string |
extraTitleInfo |
string |
favorite |
boolean |
helpLink |
string |
hidden |
boolean |
id |
string |
metricViews |
< AnalyticsMetricView > array |
name |
string |
noAccess |
boolean |
polarity |
enum (positive, negative) |
precision |
integer (int32) |
reportTimeAttribution |
boolean |
segmentable |
boolean |
shares |
< Share > array |
support |
< string > array |
supportsDataGovernance |
boolean |
tags |
< Tag > array |
title |
string |
type |
enum (STRING, INT, DECIMAL, CURRENCY, PERCENT, TIME, ENUM, ORDERED_ENUM) |
usageSummary |
|
visibility |
enum (visibleEverywhere, builderOnly, hiddenEverywhere) |
warning |
AnalyticsMetricView
place holder description
Example
{ "Place holder example":""}
Fields
| Name | Schema |
|---|---|
description |
string |
id |
string |
name |
string |
AnalyticsReportSuite
| Name | Description | Schema |
|---|---|---|
active |
boolean |
|
baseUrl |
string |
|
calendarAnchorDate |
string (date-time) |
|
calendarType |
||
companyId |
integer (int32) |
|
currency |
string |
|
currentTimezoneOffset |
number (float) |
|
dataCurrentAsOf |
string (date-time) |
|
defaultPage |
string |
|
ipObfuscationEnabled |
boolean |
|
isBlocked |
boolean |
|
isDeleted |
boolean |
|
lastModified |
string (date-time) |
|
localizationEnabled |
boolean |
|
numGroups |
integer (int32) |
|
parentRsid |
Parent report suite id for virtual report suite |
string |
relatedCompanies |
< RelatedCompany > array |
|
reportSuiteName |
Friendly report suite name |
string |
rsid |
report suite id |
string |
signedUpDate |
string (date-time) |
|
timezone |
integer (int32) |
|
timezoneZoneinfo |
Suite friendly timezone name |
string |
AnalyticsReportSuiteDataRetentionSettings
| Name | Schema |
|---|---|
fragKeyMonths |
integer (int32) |
fragMonths |
integer (int32) |
fragNonKeyMonths |
integer (int32) |
fragSubRelMonths |
integer (int32) |
getdWMonths |
integer (int32) |
retentionMessage |
string |
retentionStatus |
string |
AnalyticsSegmentResponseItem
This object contains the response for a segment GET operation.
Example
{
"id":"s300006369_5aa194ef3e958a49fd76e5b2",
"name":"Test Segment 1",
"description":"",
"rsid":"adbedocrsid",
"owner":{"id":796785}
}
Fields
Every response will contain the following fields:
-
id - The segment ID
-
name - The segment name
-
description - The segment description
-
rsid - The segment’s associated report suite ID
-
owner - The user id of the owner of this segment
Other fields can be requested via the 'expansions' option in the request parameters:
-
modified - Date that the segment was last modified (ISO 8601)
-
definition - Segment definition as JSON object
-
compatibility - Products that the segment is compatible with
-
reportSuiteName - Also return the friendly Report Suite name for the RSID
-
legacyId - Legacy segment ID from old segment database (only exists if the segment was migrated from the old segment DB)
-
dwInUse - True if the segment is currently in use in a DW request
-
asiInUse - True if the segment is currently in use in an ASI slot
-
aamStatus - Returns AAM/Raven publishing status (cross-product segment sharing)
-
favorite - True if segment has been marked as a 'Favorite'
-
tags - Gives all existing tags associated with the segment
-
approved - True if segment has been marked as 'Approved'
-
shares - Gives all existing shares for the segment
-
sharesFullName - Give 'shares', but also include the shared-to user’s friendly login name as 'shareToDisplayName' in each share object
-
ownerFullName - Add friendly full login name (string) to the 'owner' object
-
isDeleted - Returns whether or not the segment is 'Deleted' (note that deleted segments are only returned if requested by ID
| Name | Description | Schema |
|---|---|---|
aamStatus |
AAM/Raven publishing status (cross-product segment sharing). A segment can be published to AAM, and this flag indicates whether the segment has been published to AAM. |
< string, object > map |
alternateVariableNames |
||
approved |
Whether or not the segment has been marked approved. |
boolean |
asiInUse |
Whether or not the segment currently in use in an ASI (old version of VSR) slot. |
boolean |
compatibility |
Analytics products that the segment is compatible with |
< string, object > map |
created |
string (date-time) |
|
curatedItem |
boolean |
|
customerJourney |
boolean |
|
dataGroup |
The data group of the segment |
string |
definition |
The segment definition as a JSON object |
< string, object > map |
description |
A description of the segment. |
string |
dwInUse |
Whether or not the segment currently in use in a Data Warehouse request. A Data Warehouse request is another type of report that clients can run based on their raw data |
boolean |
favorite |
Whether or not the segment has been marked as a favorite. |
boolean |
id |
Id of the segment. |
string |
isDeleted |
Whether or not the segment is 'Deleted' (deleted segments are only returned if requested by id) |
boolean |
legacyId |
Legacy segment id from old segment database (only exists if the segment was migrated from the old segment DB) |
string |
modified |
string (date-time) |
|
name |
A name for the segment. |
string |
organization |
string |
|
owner |
The owner of the segment as an Owner object. |
|
reportSuiteName |
The friendly name for the report suite id. |
string |
reportTimeAttribution |
boolean |
|
rsid |
The report suite id. |
string |
shares |
Existing shares for the segment. |
< Share > array |
siteTitle |
A name for the report suite. This is deprecated and should use the report suite name instead. |
string |
tags |
All existing tags associated with the segment. |
< Tag > array |
template |
Whether or not the segment is a template. A template is a predefined segment that can be used by all customers and can not be edited |
boolean |
usageSummary |
How frequently the user uses this segment. |
|
version |
string |
|
virtualReportSuites |
A list of all Virtual Report Suites that are using this segment. |
< AnalyticsVirtualReportSuite > array |
AnalyticsTrackingServer
| Name | Description | Schema |
|---|---|---|
trackingServer |
The server to which a company’s tracking data is sent |
string |
AnalyticsVRSCompatibility
| Name | Schema |
|---|---|
message |
string |
supported_products |
< string > array |
valid |
boolean |
validator_version |
string |
AnalyticsVirtualReportSuite
| Name | Description | Schema |
|---|---|---|
alternateVariableNames |
||
approved |
boolean |
|
axleConfig |
||
calendarType |
||
compatibility |
||
created |
string (date-time) |
|
curatedComponents |
< AnalyticsCuratedComponent > array |
|
curationEnabled |
boolean |
|
currency |
string |
|
currentTimezoneOffset |
number (float) |
|
darkSessionsEnabled |
boolean |
|
dataCurrentAsOf |
string (date-time) |
|
dataSchema |
string |
|
description |
string |
|
discoverUiEnabled |
boolean |
|
enabledSolutions |
< string > array |
|
favorite |
boolean |
|
globalCompanyKey |
string |
|
groups |
< UserGroup > array |
|
id |
System generated virtual report suite id |
string |
isBlocked |
boolean |
|
isDeleted |
boolean |
|
modified |
string (date-time) |
|
name |
string |
|
numGroups |
integer (int32) |
|
numericRsid |
integer (int32) |
|
owner |
||
parentRsid |
Parent report suite id for virtual report suite |
string |
parentRsidName |
Parent report suite name |
string |
remoteLoading |
boolean |
|
reportSuiteName |
The report suite name for which the component was created/updated |
string |
rsid |
The report suite id for which the component was created/updated |
string |
segmentList |
List of segments applied to this virtual report suite |
< string > array |
sessionDefinition |
||
shares |
< Share > array |
|
siteTitle |
string |
|
tags |
< Tag > array |
|
taxonomist |
boolean |
|
timezone |
integer (int32) |
|
timezoneZoneinfo |
Suite friendly timezone name |
string |
usageSummary |
Approval
Approval is an object representing a component that has been approved by an admin user. Approvals allow other users in an Analytics company to know which components have been tested, reviewed and can be relied upon.
Here a some examples of components that can be approved: Segments, CalculatedMetrics, Projects
| Name | Description | Schema |
|---|---|---|
approvalId |
A system generated approval id |
integer (int64) |
approvalTimestamp |
The timestamp for when this approval was last updated |
string (date-time) |
companyId |
The Analytics company id for which this approval was created |
integer (int32) |
componentId |
The id of the component for which to create an approval |
string |
componentType |
The component type |
enum (segment, dashboard, bookmark, calculatedMetric, project, dateRange, metric, dimension, virtualReportSuite, scheduledJob, alert, classificationSet) |
componentTypeId |
The component type id which is determined by the componentType |
integer (int32) |
userId |
The Analytics user id of the user that created this approval |
integer (int32) |
AttributionModel
| Name | Schema |
|---|---|
context |
string |
expiration |
|
firstWeight |
integer (int32) |
func |
enum (ALLOCATION_FIRST_TOUCH, ALLOCATION_LAST_TOUCH, ALLOCATION_INSTANCE, ALLOCATION_LAST_KNOWN, ALLOCATION_LEGACY, ALLOCATION_LINEAR, ALLOCATION_PARTICIPATION, ALLOCATION_POSITION_BASED, ALLOCATION_TIME_DECAY, ALLOCATION_U_SHAPED, ALLOCATION_J_SHAPED, ALLOCATION_REVERSE_J_SHAPED) |
halfLifeGranularity |
string |
halfLifeNumPeriods |
integer (int32) |
lastWeight |
integer (int32) |
merchandising |
|
middleWeight |
integer (int32) |
BatchDataGovernanceSettings
| Name | Schema |
|---|---|
auth |
|
gdprAccess |
|
gdprDelete |
|
identifiability |
|
namespace |
string |
sensitivity |
|
status |
|
variableId |
string |
CalcMetricCompatibility
| Name | Schema |
|---|---|
functions |
< string > array |
identityDimensions |
< string > array |
identityMetrics |
< IdentityMetric > array |
message |
string |
segments |
< string > array |
supported_products |
< string > array |
supported_schema |
< string > array |
valid |
boolean |
validator_version |
string |
CalcMetricFunction
The Calculated Metric Function is used to define the names and types of parameters expected for each function. It is referenced in the Calculated Metric Definition by id.
Example
{
"id": "divide",
"category": "internal",
"persistable": true,
"definition": {
"func": "calc-metric",
"parameters": [
{
"func": "parameter-def",
"name": "col1",
"type": "column"
},
{
"func": "parameter-def",
"name": "col2",
"type": "column"
}
],
"version": [1,0,0]
}
}
| Name | Schema |
|---|---|
category |
string |
definition |
|
description |
string |
example |
string |
exampleKey |
string |
id |
string |
name |
string |
namespace |
string |
persistable |
boolean |
CalcMetricFunctionDef
Calculated Metric Function Definition model
| Name | Schema |
|---|---|
formula |
< string, object > map |
func |
string |
parameters |
< CalcMetricFunctionParameter > array |
version |
< integer (int32) > array |
CalcMetricFunctionParameter
Calculated Metric Function Parameter model
| Name | Schema |
|---|---|
default-value |
object |
descKey |
string |
description |
string |
friendlyName |
string |
friendlyNameKey |
string |
func |
string |
name |
string |
type |
string |
CalculatedMetricAuthorization
| Name | Schema |
|---|---|
authorized |
boolean |
unAuthorizedMetricIdentities |
< string > array |
unAuthorizedSegmentIds |
< string > array |
CalculatedMetricDef
The Calculated Metric Def object contains the metrics and functions that define the calculations to be made in a calculated metric.
To see metrics available to be used in Calculated metrics call the
API endpoint. (For more information on the metric schema see AnalyticsMetric)/metrics
To see functions available to be used in calculated metrics call the