Reporting API

This document describes the RTI Business Intelligence API. The API exposes our Data Warehouse through REST API. As a result this enables seamless integration with clients and existing dashboards. RTI VUE is an example of the integration of the REST API to our BI data.

Please see Thor Reporting Functional Specs for groupings dimensions, and metrics definitions for additional info.

Overview

The RTI Business Intelligence API enables our customers to have direct access to important data related to their use of Kibo Solutions through an always-available REST API. This data can then be incorporated into executive dashboards or other BI tools giving key decision makers a view of the system’s performance on a regular basis. The API allows customers to choose from a list of available metrics, and specify a time period and format (CSV or JSON).

Benefits

Direct access to the data via an open API
Run real-time queries or store data onsite for larger, more complex reports.
Create a script to run automatically every day, saving you time.
Access large amounts of data – the file size is only limited by your capacity to consume it
Baynote maintains at least 2 years of data for each of our customer instances

Framework

We provide most reports in real-time including custom views of the BI data.
The BI solution leverages our Big Data infrastructure including Hadoop and Hive and exposes the data via a Real Time tier of SQL Servers.
RTI produces the data using reporting jobs that are typically run on a nightly basis and moving to a combination of real-time update and batch updates (Lambda architecture).

Structure of the REST URLs

To use a REST API, your application will make an HTTP request and parse the response.

The BI REST API uses csv, json and html as its output formats. It is a read-only API. The standard HTTP method GET is used to access reporting resources. URLs for Reporting REST API have the following structure:

http://host:port/BI/VERSION/SITE/resource-name?<parameters>

where

SITE: CN_CC
VERSION: 1

Security

The API leverages AAA for access leveraging Spring Security.

Sample Request to Production

production: http://prod-rpt01:8080 (e.g. http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01)

prod sample calls

http://prod-rpt01:8080/BI/1/lumber_www/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/theknot_shop/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01
http://prod-rpt01:8080/BI/1/netshoes_mx/dailytotalsmetrics?page=1&size=10

Resources

Totals

dailytotalsmetrics
weeklytotalsmetrics
monthlytotalsmetrics

Attributes

dailyattributesmetrics
weeklyattributesmetrics
monthlyattributesmetrics

Products

dailyproductsmetrics
weeklyproductsmetrics
monthlyproductsmetrics

Recs

dailyrecsmetrics
weeklyrecsmetrics
monthlyrecsmetrics

Tests

dailytestsmetrics
weeklytestsmetrics
monthlytestsmetrics

Email

dailyemailmetrics
weeklyemailmetrics
monthlyemailmetrics

Security

The API leverages AAA for access leveraging Spring Security.

Sample Request to Production

production: http://prod-rpt01:8080 (e.g. http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01)

prod sample calls

http://prod-rpt01:8080/BI/1/lumber_www/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/theknot_shop/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01
http://prod-rpt01:8080/BI/1/netshoes_mx/dailytotalsmetrics?page=1&size=10

Common Parameters

Filter by data

Start

Optional. Indicates beginning of the reporting range. Date/time values are expressed in ISO 8601 format. If the time falls within a period and is not at the beginning of a period, then that period is included in the returned data.

End

Optional. Indicates the end of the reporting range. Date/time values are expressed in ISO 8601 format. If this parameter is not specified, the current time is assumed. If the time is within a period, then the last partial period is not included in the returned data.

You can specify an api call without start and end, with both start and end, or just the start or just the end.

Pagination

Pagination is supported by two optional formats: page and size. They can be used together with start and end or on its own.

Note, it works together with start and end parameters.

start and end filter result set.
page and size paginate the result set

If you specify pagination, start and end filter by date. Pagination is applied whether or not start and end have been used.

page

An optional parameter that specifies which page of results to return. Works together with size; 1-based.

size

An optional parameter that specifies number of results per page to return. Works together with page. If page is not specified, the page is set to 1 by default. If neither page or size are specified, then all the results will be returned.

Output Format

format

Indicates the encoding of the returned data. csv, json, and html can be specified by using this parameter (e.g. …&format=csv…).

The default output format is HTML. All data contains headers.

Aggregation

sumBy

An optional parameter that mimics SQL GROUP BY in conjunction with the SUM aggregate function. Specifying this parameter forces all metrics to be summed for given dimension(s).

Notes:

For Totals it does not make sense, since totals resources contain only one dimension (Date).
This parameter is case-sensitive.

Let’s view attributes as an example. Here is simple data:

Date	Attribute1	Attribute2	Rec Clicks	Directed items	Other metrics
1	men	pants	2	11	…
1	men	skirt	3	12	…
1	women	pants	4	13	…
1	women	skirt	5	14	…
2	men	pants	6	15	…
2	men	skirt	7	16	…
2	women	pants	8	17	…
2	women	skirt	9	18	…

sumBy=RecordDate

Date	Rec Clicks	Directed Items	Other metrics
1	14	50	…
2	30	66	…

sumBy=Attribute1

Attribute1	Rec Clicks	Directed Items	other metrics
men	18	54	…
women	26	63	…

sumBy=RecordDate, Attribute1

Date	Attribute1	Rec Clicks	Directed Items	Other metrics
1	men	5	23	…
1	women	9	27	…
2	men	13	31	…
2	women	17	35	…

You may wonder if the number of sum by parameters is limited to 2. Can you have sumBy=date,attribute1,attribute2?

It does not make sense to do that. In this case you would be summing by all three dimensions. Note: date, attribute1, attribute2 combination should be unique. In fact, if allthree are specified in sumBy, then the output should be identical to the output wihtout any sumBy at all.

What about other groupings? It’s case by case. For instance, totals has only 1 dimension: date. It does not make sense to use any sumBy there. Attributes has 3: date, attribute1, attribute2. In that case it makes sense to use no more than 2 dimensions in sumBy. Products has 2 dimensions: date and product id. In this case it makes sense to use no more than 1 dimension in the sumBy (either date or product id).

Sorting

orderBy

An optional parameter that sorts default output data by a particular grouping of dimensions in ascending order. If orderby is specified, then the output data is sorted by whatever it is specified as orderby value that is valid for that particular grouping. It also specifies whether the sort order is ascending or descending. Note, the parameter is case sensitive.

In more detail…

If no orderBy is given, the system sorts in ASC order by default, using all the dimensions in that grouping.

totals: recordDate
products: recordDate, prodcutId
attributes: recordDate, Attribute1, Attribute1
recs: recordDate, test group, recSpec
email: recordDate, campaign

Example

 orderBy=directedItems:ASC,recclicks:DESC

In this case, directedItems is sorted in ASC order, and recClicks in DESC.

Note: for MVP orderBy would only support passing one parameter.

If no ASC/DESC is given for a parameter, then the system uses ASC by default. This is what SQL-92 complaint dbs do.

Resources

Totals

dailytotalsmetrics
weeklytotalsmetrics
monthlytotalsmetrics

Dimensions

recordDate

Metrics

Unique Visitors
Rec Users
Total Clicks
Rec Clicks
Visits
Page Views
Lingers
Rec impressions
Rec Widget impressions
Rec engagements
Directed Orders
Directed Orders Revenue
Directed Items
Directed Items Revenue
Influenced Orders
Influenced Orders Revenue
Influenced Items
Influenced Items Revenue
total Orders
Total Orders revenue
Total items revenue

Examples

/dailytotalsmetrics?format=csv&start=2013-03-09

/dailytotalsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklytotalsmetrics?format=json&start=2013-03-09

/weeklytotalsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlytotalsmetrics?format=html&start=2013-03-09

/monthlytotalsmetrics?format=json&start=2013-03-09&end=2013-4-10

Attributes

dailyattributesmetrics
weeklyatributesmetrics
monthlyattributesmetrics

Dimensions

recordDate
Attribute1 (configurable. e.g. Category)
Attribute2 (configurable. e.g. Sub-Category)

Metrics

Red Clicks
Directed Items
Directed Items Revenue
Influenced Items
Influenced Items Revenue
Rec impressions
Rec Widget impressions

Examples

/dailyattributesmetrics?format=csv&start=2013-03-09

/dailyattributesmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyattributesmetrics?format=json&start=2013-03-09

/weeklyattributesmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyattributesmetrics?format=html&start=2013-03-09

/monthlyattributesmetrics?format=json&start=2013-03-09&end=2013-4-10

Products

dailyproductsmetrics
weeklyproductsmetrics
monthlyproductsmetrics

Dimensions

recordDate
Products (Top 50 products sorted by Directed Items Revenue)
- product id (product id attribute name is configurable)
- product name (product name attribute name is configurable)

Metrics

Rec Clicks
Directed Items
Directed Items Revenue
Influenced Items
Influenced Items Revenue
Rec impressions
Rec Widget impressions

Examples

/dailyproductsmetrics?format=csv&start=2013-03-09
/dailyproductsmetrics?format=html&start=2013-03-09&end=2013-4-10
/weeklyproductsmetrics?format=json&start=2013-03-09
/weeklyproductsmetrics?format=csv&start=2013-03-09&end=2013-4-10
/monthlyproductsmetrics?format=html&start=2013-03-09
/monthlyproductsmetrics?format=json&start=2013-03-09&end=2013-4-10

Recs

dailyattributesmetrics
weeklyattributesmetrics
monthlyattributesmetrics

Dimensions

recordDate
testGroup
recSpec

Metrics

Rec Clicks
Directed Orders
Directed Orders Revenue
Directed Items
Directed Items Revenue
Influenced Orders
Influenced Orders Revenue
Influenced Items
Influenced Items Revenue
Rec impressions
Rec Widget impressions
Rec engagements

Examples

/dailyrecsmetrics?format=csv&start=2013-03-09

/dailyrecsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyrecsmetrics?format=json&start=2013-03-09

/weeklyrecsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyrecsmetrics?format=html&start=2013-03-09

/monthlyrecsmetrics?format=json&start=2013-03-09&end=2013-4-10

Tests

Dimensions

recordDate
testName
testGroup

Metrics

Rec Clicks
Rec Users
Directed Items
Directed Items Revenue
Directed Orders
Directed Orders Revenue
Influenced Items
Influenced Items Revenue
Influenced Orders
Influenced Orders Revenue
Rec impressions

Examples

/dailytestsmetrics?format=csv&start=2013-03-09

/dailytestsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklytestsmetrics?format=json&start=2013-03-09

/weeklytestsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlytestsmetrics?format=html&start=2013-03-09

/monthlytestsmetrics?format=json&start=2013-03-09&end=2013-4-10

Email

Dimensions

recordDate
campaign

Metrics

Email Clicks
Directed Orders
Directed Orders Revenue
Directed Items
Directed Items Revenue
Influenced Orders
Influenced Orders Revenue
Influenced Items
Influenced Items Revenue

Examples

/dailyemailmetrics?format=csv&start=2013-03-09

/dailyemailmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyemailmetrics?format=json&start=2013-03-09

/weeklyemailmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyemailmetrics?format=html&start=2013-03-09

/monthlyemailmetrics?format=json&start=2013-03-09&end=2013-4-10

RESOURCE CENTERRTI DOCUMENTATION

Kibo RTI Development

Documentation

Reporting API

Overview

Benefits

Framework

Structure of the REST URLs

Security

Sample Request to Production

Resources

Totals

Attributes

Products

Recs

Tests

Email

Security

Sample Request to Production

Common Parameters

Filter by data

Pagination

page

size

Output Format

format

Aggregation

sumBy

Sorting

orderBy

Resources

Totals

Dimensions

Metrics

Examples

Attributes

Dimensions

Metrics

Examples

Products

Dimensions

Metrics

Examples

Recs

Dimensions

Metrics

Examples

Tests

Dimensions

Metrics

Examples

Email

Dimensions

Metrics

Examples

Release Notes

Contact Us

Learn More