Analytics API

[isaac-ewing]

Hi whoever knows the answers,

I have several questions... after going through the analytics api 1.4 documentation, i realized it doesn't help answer any of the following:

1.) how do i build multi-segment api requests

-i.e. device type = mobile, not tablet, some other condition - without creating a new segment in the dashboard

2.) how do i build multi-metric api requests

-i.e. the documentation says metric[ {id: value} ]... cool but why does the following work

"metrics":[{

"id":"uniquevisitors",

"element":"evar13",

"selected":[

"/some-website-page.html"

]}]

my point is, how do i add queries like this and what are all the properties and argument types

3.) how do i build multi-dimension api requests

-i.e a target activity (let's say experience) that has a page with two or three variants, how do i correctly built that type of request and what are all the properties and settings that i can use

4.) why do the numbers in the api not match the gui in analytics, let's say for visitors or unique visitors, how do i add the property that says don't count repeat visitors or whatever it is you do in the gui. what are all the properties a report description can contain.

5.) for god sakes, why did you deprecate the target api inside the analytics api, if someone only has access to the target api, how do you query a list of campaigns or maybe just ab tests or whatever, and how do you do it without using the data warehouse to get a zillion urls that need to be mapped one by one.

there's a lot more questions but i don't want to type them if no one knows the answer. its obviously possible since the workspace dashboard can do it and i've gone through the ajax requests it makes but the naming conventions, structure of the data and format don't match. maybe someone at adobe can help with these extremely frustrating questions.

thanks,

isaac

[Alexis_Cazes_ · Accepted solution]

Hi Isaac,

I am going to answer some questions and hopefully it will help you.

First to see what the request should look like with all of the options either use the api explorer (you do not need to input username and password to see default structure, simply select api Report and Method Queue ) or you could use swagger (Notice in Example Value you should see full structure of request). Right so not all fields are required to do a request and I will try to give example a bit later on.

How do i build multi-segment api requests

Ok so I think one of the solution would be to use inline segmentation

Another solution would be to apply filtering in the elements themselves:

Check reportDescriptionElement and reportDescriptionSearchType

(notice the element searches: this will allow you to create multiple searches, so first level would be type and and inside searches the different ones like not).

How do I build multi-metric api requests

You will need to specify different metric ids. (I do not know why you example works)

{
   "reportDescription":{
      "reportSuiteID":"reportSuiteId",
      "dateFrom":"YYYY-MM-DD",
      "dateTo":"YYYY-MM-DD",
      "metrics":[
         {
            "id":"uniquevisitors"
         },
         {
            "id":"event27"
         },
         {
            "id":"event28"
         },
         {
            "id":"event29"
         },
         {
            "id":"event30"
         },
         {
            "id":"event31"
         },
         {
            "id":"event32"
         },
         {
            "id":"cm2566_5adf02ff7245ec54ba3e7317"
         },
         {
            "id":"cm2566_5adf01f90d38c21db0b2ba88"
         },
         {
            "id":"cm2566_5adf037102f60c51b92c5d5f"
         },
         {
            "id":"cm2566_5adf03a57a877de82a990a97"
         },
         {
            "id":"cm2566_5adf04051d84534d9a98e6d9"
         },
         {
            "id":"cm2566_5adf0424366e5b4688b4c62d"
         },
         {
            "id":"cm2566_5adf046155bf155cfbf0af5e"
         },
         {
            "id":"cm2566_5a4ba8b31d84536d599b3a99"
         }
      ],
      "segments":[
         {
            "id":"s2566_598b2c8b0d38c26a449bf986"
         },
         {
            "id":"s2566_59c37616dd0ab15248d5a6bd"
         },
         {
            "id":"s2566_59c4dfa9de89edf2ca867650"
         },
         {
            "id":"s2566_597b01f70d38c20a175cd5d0"
         }
      ],
      "currentData":"true",
      "elementDataEncoding":"utf8"
   }
}

Notice that in the request above I specified default metrics (eventx) but also calculated metrics (cmXXXXX).

You will also notice that I used stacking segments as well.

How do i build multi-dimension api requests

I did not work with target data much so I won't be able to provide any insight target wise.

Having said that I think if you want to extract data where a dimension can be X or Y or Z then use one this solution:

- Segments: create either one segment with OR condition or multiple segments that you can stack up as above.

- Use elements filtering to filter only for value X, Y, Z

- Use inline segmentation as above.

If you want to get more than one dimension in the report then you will need to define more than one element.

{
   "reportDescription":{
      "reportSuiteID":"rsid",
      "dateFrom":"YYYY-MM-DD",
      "dateTo":"YYYY-MM-DD",
      "metrics":[
         {
            "id":"uniquevisitors"
         },
         {
            "id":"event27"
         },
         {
            "id":"event28"
         },
         {
            "id":"event29"
         },
         {
            "id":"event30"
         },
         {
            "id":"event31"
         },
         {
            "id":"event32"
         },
         {
            "id":"cm2566_5adf02ff7245ec54ba3e7317"
         },
         {
            "id":"cm2566_5adf01f90d38c21db0b2ba88"
         },
         {
            "id":"cm2566_5adf037102f60c51b92c5d5f"
         },
         {
            "id":"cm2566_5adf03a57a877de82a990a97"
         },
         {
            "id":"cm2566_5adf04051d84534d9a98e6d9"
         },
         {
            "id":"cm2566_5adf0424366e5b4688b4c62d"
         },
         {
            "id":"cm2566_5adf046155bf155cfbf0af5e"
         }
      ],
      "elements":[
         {
            "id":"evar9",
            "top":"200",
            "search":{
               "type":"not",
               "keywords":"FILTER1"
            }
         },
         {
            "id":"evar37",
            "top":"200",
            "search":{
               "type":"or",
               "keywords":"FILTER2"
            }
         },
         {
            "id":"evar7",
            "top":"200"
         }
      ],
      "segments":[
         {
            "id":"s2566_598b2c8b0d38c26a449bf986"
         },
         {
            "id":"s2566_59c37616dd0ab15248d5a6bd"
         },
         {
            "id":"s2566_59c4dfa9de89edf2ca867650"
         },
         {
            "id":"s2566_597b01f70d38c20a175cd5d0"
         }
      ],
      "currentData":"true",
      "expedite":true,
      "elementDataEncoding":"utf8"
   }
}

One more thing, there is an API to create segments as well on fly, so you could always use this API before calling the Reporting API to do dynamic segmentation. I have a project internally when we run a ruby script to update a set of segments before the analysis workspace scheduled report run each week which allows us to not update the segments manually each week.

That is all from me.

Best regards.

Alexis Cazes

[isaac-ewing]

Hi Alexis,

Thanks for the reply, your answer was a pleasant surprise. Although it was helpful, I was able to derive the information you sent, through the limited documentation. I was hoping for more advanced techniques. For example, I knew about the API explorer and the swagger resource from the online documentation. I knew about the inline segments as well as the various data types to use for the endpoints.

The example I sent works with both itemsId and items and item.

The multidimensional metric question was more about creating metrics that are very precise rather than throwing in a whole bunch into a single API request. The example you sent is helpful but I was hoping to get more insight into creating ultra-targeted metrics... but your response was indeed helpful.

As far as the part about multidimensional dimension requests, that should have been more clear when I typed the question, I meant, let's say we have a target activity (let's say it's an experience activity). In the experience dimension, we have two pages (variant and control). Cool, so if we were in workspace, imagine what that looks like and now, on the metrics area of the dimension, we have two parts. One the first (left portion of the metrics, we have a metric (unique visitors) and under it is a page URL dimension (/this/is/wonderful.html). Cool, on the second part (the right most of the dimension), we have a metric (unique visitors) and under it is a page URL dimension (/this/is/awesome.html) and under that bad boy we have a hit segment that tests for a name that could equal a number of different name values. So that's an example of what I meant by multidimensional metrics. I simply do not know how to replicate that in an API request.

As for the segment API information, I am familiar with it although I didn't think to create a request that will update a segment on the fly, that's an interesting idea.

Another issue I've been struggling to create a solution for is how do i send requests specific to an activity or experience (as in: when you search for someone or something in any other API, you will almost always pass in the id of that object), instead of creating filters and metrics and segmenting those things, how do I do it with analytics (that's why I sent the example of items example, it works, give it a try). For example, the below snippet works:

"elements":[

     {

          "id":"experience",

          "items":[

               "1621921405"

          ]

     }

]

Additionally, is there a way to query the activity list (like you would do with the target API) but without using the target API, I don't have access to it and it's been a real pain to get it so I was curious if there was a way around it. I tried every endpoint in the deprecated target API inside the analytics suite of API's but of course, it didn't work, I was curious if you have a work-around.

Finally, and this is by far the most important question of all... In workspace, I create a typical panel with the above mentioned pieces and set the dimension to a target activity > experience...

A.) there's nothing about setting the element to activity or experience but they both work... why is that.

B.) The numbers from the API request do not match the numbers in the GUI of the dashboard in analytics and I cannot figure out or understand why. I have copied the entire panel and just to make sure it's all set correct, I created a custom segment that concatenates all the segments into one and applied that single segment to the request along with set the metric to unique visitors and set the element to the above code snippet and the unique visitors per day for the two experience activities never matches the values in the dashboard. The weird thing is the breakdown total always matches but the variant and control activities never match the GUI. The totals value also never matches. The values from the API are usually always higher (once in a while, they will be lower). Anyway, I think it's because I need to add another filter such as "don't count repeat visitors" or something similar to that so it strips out more users but again, I have no idea what that would be and there's nothing in the documentation about that. I tried the following (but unfortunately, this time, the custom code didn't work, if you're wondering where I got those names and values, it's from inspecting the API requests the GUI sends to the backend):

"metrics":[

     {

          "id":"uniquevisitors",

          "countRepeatInstances":"true",

          "dimensionSort":"asc",

          "limit":"50000"

     }

]

Anyway, thank you for your help, if you could help answer the last question as it takes precedence over the others, that would be super helpful, anything past that would be a dream come true. Thank you for your help..

[Alexis_Cazes_]

Hi Isaac,

I will try to answer some of your questions in a future comment (just don't have time right now).

Having said that I realised while the Reporting API 1.4 allows you to extract data from Analytics, I think it was original designed to reproduce reports that you can build under the tab Report in Adobe Analytics. I think all the features from Analysis Workspace might not be easily reproducible via the Reporting API.

Having said that you would have noticed that the API request and response from Analysis Workspace are different in format that those from Analytics Report API 1.4, and there is a reason for that because it is another set of APIs. For a context all Adobe Products, tools and website soon will have to go through Adobe I/O. If you have not heard of Adobe I/O I would suggest you to take a look Adobe I/O . As far as I know most of the new APIs are being developed to go through Adobe I/O as well. There also some cool real-time APIs that you can leverage (i.e: Documentation  ). Using this real-time APIs you could create real-time personalisation for your customers: adobeio-solutions-documentation/Adobe-IO-Runtime-Triggers-Launch-Target.md at master · adobeio/adobe...

Having said that some month ago I found out that at the summit they presented the Analytics API through Adobe I/O: GitHub - Adobe-Experience-Cloud/analytics-io-lab

What is interesting about this, is that the API that they showcase in this tutorial is the one used by Analysis Workspace (just realised it while reading the tutorial in details.) There is a way to see the exact requests that are being used for each data source table in Analysis Workspace: analytics-io-lab/sections/s5_tips_tricks at master · Adobe-Experience-Cloud/analytics-io-lab · GitHu...  

Check the documentation of this API here Analytics Services APIs

So if I do a report as follow:

Then the request will look as follow:

{

    "rsid": "bpsapipelines",

    "globalFilters": [

        {

            "type": "dateRange",

            "dateRange": "2018-07-01T00:00:00.000/2018-08-01T00:00:00.000"

        }

    ],

    "metricContainer": {

        "metrics": [

            {

                "columnId": "1",

                "id": "metrics/occurrences",

                "sort": "desc",

                "filters": [

                    "0"

                ]

            },

            {

                "columnId": "2",

                "id": "metrics/occurrences",

                "filters": [

                    "1"

                ]

            }

        ],

        "metricFilters": [

            {

                "id": "0",

                "type": "breakdown",

                "dimension": "variables/timepartampm",

                "itemId": "0"

            },

            {

                "id": "1",

                "type": "breakdown",

                "dimension": "variables/timepartampm",

                "itemId": "12"

            }

        ]

    },

    "dimension": "variables/operatingsystemgroup",

    "settings": {

        "countRepeatInstances": true,

        "limit": 50,

        "page": 0

    },

    "statistics": {

        "functions": [

            "col-max",

            "col-min"

        ]

    }

}

You would notice that while I used one metric that represent a column, each item AM and PM under the metric is actually one metricFilters for the particular metric.

[isaac-ewing]

Well, that is great news, that would solve all the issues we've been discussing as well as a few we haven't talked about. Do you have any idea or estimate of when the analytics v2 API will be released to the public or at least allow me to signup for beta testing it.

Also, I wanted to dabble with the v2 of the analytics API but realized I don't know the password and although the tutorial is great, I cannot figure out how to access to Swagger API without the Summit 2018 credentials. Any help with that would be super helpful as well.

[Alexis_Cazes_]

I will try to get back to you tomorrow with more details. Working on using this API for quite some days now and having some issues to go around due to undocumented aspects.

What I figured out is that while it was show cased at the Summit some people said that the current API should not be customer facing ... However I talked internally at Adobe and they said that v2 of this API should be available "soon". To be honest I do not know what to expect in terms of timeframe wit just a "soon" answer. If I have to guess I would say that it might be available in next major releases like fall release maybe.

For the credentials I will provide more details tomorrow.

[Alexis_Cazes_]

The solution that I am going to describe her is to use with curl commands. One thing to be aware of is as of now the v1 of the Analytics API for Analysis Workspace does not support a way to generate the access_token programatically, what I mean by that is that using the Adobe I/O integration you will always have the step to enter your username and password.

Using Adobe Analytics interface

Using the debugger to get request and access_token

1. Go to Analysis Workspace and open the report that you want to reproduce via API.
2. Open a the developer console in your browser and input

   adobe.tools.debug.includeOberonXml = true

3. Reload the page and you should see an orange bug next to each table and visualisations
4. Click on the orange bug
5. Click on Freeform tables
6. Select entry with the most up to date date
7. A screen should be displayed with title Oberon request

What you are interested is in the JSON request. so copy it somewhere to reuse later.

You will also notice a CURL request section. You will notice the he curl request is build for you with the access token, the json request and which server to send the request to. I would advise you to set includeOberonXml to false.

The final request should look as follow (based on the report screenshot that I provided in previous post):

Using the developer console to get access_token

You can also get the access token while you are in Adobe Analytics doing the following:

1. Open the developer console
2. Input

   adobe.analytics.appConfig.appService.token

3. The access token should be displayed.

Using Adobe I/O

Ideally you would want to use Adobe I/O to get the access token. You will need to create an Adobe Analytics integration using the Adobe I/O console.

1. Api Integration:

Adobe I/O Console

2. Authentication:

Authentication

It is important to know that for now the Adobe Analytics Service account integration does not work while querying the Analytics API. The access_token will not be recognised as valid. It is due to some internal limitation

1. Go to Adobe I/O Console  and create and Adobe Analytics Integration using OAuth integration.

2. During the configuration use this url as redirect: https://runtime.adobe.io/api/v1/web/io-solutions/adobe-oauth-playground/callback

3. Complete the integration

4. Now open the integration details and take note of API Key (Client ID) and Client secret.

5. Go to OAuth 2.0 Playground  and add the different details and click on generate token

6. You will be redirected to log in page enter you adobe ID details and you should finally be redirected to tokens tab

You can use the access_token in same curl request as above

[marion33678522]

Hello to all,

So if I understood well, all the old Api requests to the report Api will be obsolete ?

I started working in a way to automate data extraction using the API , and we started using a python library that helps us to connect to the API and extract all the metrics using segments IDs.

Cheers !

[Alexis_Cazes_]

As far as I know Adobe Analytics API 1.4 has not been sunset yet so it is still valid. However this API cannot reproduce the Analysis Workspace reports in one request, it most likely will take more than one request to reproduce some the tables from Analysis Workspace.

The new Analytics API that I mentioned in the post above is the one used behind Analysis Workspace and the v2 version should be available soon as per I was told. This API will require to authenticate via Adobe I/O integration unlike Adobe Analytics API 1.4.

Maybe Gigazelle​ can provide more details on the future of the Adobe Analytics API 1.4 .

[Gigazelle]

Just had a meeting yesterday with the API team

The 1.4 API will not be going away soon (at least a year, maybe more). The v2 API needs to be in solid shape before we even think about sunsetting 1.4.

The v2 API should be available around October, and as Alexis said, will be through Adobe I/O.

[michaelk6407690]

Interesting and helpful thread.

I saw you comment

It is important to know that for now the Adobe Analytics Service account integration does not work while querying the Analytics API. The access_token will not be recognised as valid. It is due to some internal limitation

Is there a plan/target date for service accounts to work with the analytics api? We have been using 1.4 apis to integrate with Adobe on behalf of others. With the migration to cloud, we can no longer use Company.GetLoginKey to get an access key.

What is the recommended replacement?

[Alexis_Cazes_]

Did you try to use the following:

analytics-1.4-apis/auth_register_app.md at master · AdobeDocs/analytics-1.4-apis · GitHub

[michaelk6407690]

Thx. Did read that, but I think I found a solution for now. Previously our users entered their password and we could retrieve the web services secret using Company.GetLoginKey Since that no longer works for 'Cloud' users they will need to get the secret from the Adobe Analytics->Admin->User Management and enter that directly.

[elisavetf986787]

Hello,

I'm using for a long time now the API 1.4 with the python library provided in gitHub. We have a lot of automations in place running to create reports and extract data on a daily basis. I saw above that the API 1.4 will be obsolete quiet soon and I was wondering if you are going to publish a Python library for the API 2.0 so we can migrate to the API 2.0 before the 1.4 becomes obsolete.

Thanks in advance for your help.

Best,

Elisavet

[raviprasadp7863]

Is there any solution for below error:

"error_description": "The maximum number of elements supported is 4"

It can be only 4 or can we add more somehow in the elements ?