Reporting API – Extended ReportDescription

Building upon Pulling Data out of the Reporting API, we will today extend the example to include a breakdown, more metrics, a filter and a segment. We will also use the classified report rather than the non-classified for added readability.

With a more complex report like this it is even more important to have a blueprint to work from. So first of all, we’ll create the report in SiteCatalyst. This is what it looks like:

We have added:

• the Products dimension,
• the Click-throughs and Unique Visitors metrics,
• a filter that looks for specific campaign names (containing “Hamburg”),
• a segment, “first time visits”.

Note: this is very specific data. You can see that we’re looking at three visitors who clicked through three times and had a total of three visits. It is relatively unlikely that you will ever use all of the above features in one report at the same time. But we want to show how it works.

Classifications

Let’s start with the classification.

In order to pull the classified report, we need to specify the classification on the element that we’re pulling, like so:

  ReportDefinitionElement[] elements = new ReportDefinitionElement[1];
  elements[0] = new ReportDefinitionElement();
  elements[0].setId("trackingCode");
  elements[0].setClassification("Campaigns");
  reportDesc.setElements(elements);

That’s it.

Segments

Next, let’s add the segment.

In order to specify the segment, we need to know the segment ID. We can find that by querying all the segments the report suite knows. There’s a call for that called ReportSuite.GetSegments. (If you’re using Java, you’ll call stub.reportSuiteGetSegments(rs_list).)

Looking through that list, we find the id: “Visit_First”.

Adding that segment to our report is as easy as specifying it like so:

  reportdesc.setSegment_id(segmentID);

More Dimensions

Now we’ll add a breakdown by adding a new dimension or element.

  ReportDefinitionElement[] elements = new ReportDefinitionElement[2];
  elements[0] = new ReportDefinitionElement();
  elements[0].setId("trackingCode");
  elements[0].setClassification("Campaigns");
  elements[1] = new ReportDefinitionElement();
  elements[1].setId("product");
  reportDesc.setElements(elements);

The result is basically that instead of an array of values we’ll get back an array of arrays of values.

More Metrics

And to finish it all up, we will add two new metrics:

  ReportDefinitionMetric[] metrics = new ReportDefinitionMetric[3];
  metrics[0] = new ReportDefinitionMetric();
  metrics[0].setId("cVisits");
  metrics[1] = new ReportDefinitionMetric();
  metrics[1].setId("instances");
  metrics[2] = new ReportDefinitionMetric();
  metrics[2].setId("cVisitors");
  reportDesc.setMetrics(metrics);

Note how we originally said we would add “Click-throughs” to the report? In SiteCatalyst, the metric certainly is called that. In actual fact, the system uses the Instances metric in the backend, so that’s what we need to pull.

Note also that we used cVisits and cVisitors as metrics here. Those are the conversion equivalents of Visits and Unique Visitors.

Searches / Filters

Next, we add the “Hamburg” filter. Filters in the Reporting API are applied to metrics, like so:

  ReportDefinitionElement[] elements = new ReportDefinitionElement[2];
  elements[0] = new ReportDefinitionElement();
  elements[0].setId("trackingCode");
  elements[0].setClassification("Campaigns");
  ReportDefinitionSearch search = new ReportDefinitionSearch();
  search.setType(ReportDefinitionSearchType.and);
  String[] keywords = new String[1];
  keywords[0] = "Hamburg";
  search.setKeywords(keywords);
  ReportDefinitionSearch[] sub_searches = new ReportDefinitionSearch[0];
  search.setSearches(sub_searches);
  elements[0].setSearch(search);

We do not know why the declared but not defined “sub_search” needs to be in there, but it does.

The Result

When you run the report for the first time and get a result back, you’ll be surprised how many layers of arrays the Reporting API uses to hand back the report.

Our tip: use the debugger and SiteCatalyst side-by-side in order to find out what value means what and where to find a specific piece of data in that massive structure.

The red box in the screenshot encircles the same data we saw above in the screenshot from the UI. Note that we have three values here. Which one’s which?

Check the “rmetrics” structure higher up in the results. It tells you which metrics were used and in which order. In our example, the first “3” is the number of “Visits”.

Another thing to note: the totals do not match our SiteCatalyst report!

The explanation for that is that the filter works differently in SiteCatalyst versus the Reporting API. While SiteCatalyst applies the filter to values on both levels, the Reporting API only applies it on the whichever element you declare it on.

Since we only used it on one of the metrics, we see higher totals in the Reporting API (301 rather than 288 Visits).

Those of you who use PHP will have it slightly easier, plus you guys are used to these kinds of data structures. For everyone else and with complex reports, the “decoding” needs time.

Here’s another screenshot, comparing the original SiteCatalyst report with the data returned by the Reporting API. Some of the values are pointed out.

Good luck!

Next time we will introduce “segmentation on the fly”, i.e. defining a segment in the ReportDefinition. Oh the fun!