Reports & Data

Calling the available Reports

https://ws.etracker.com/api/v6/report

With this call, you can receive a list of all reports (including your own) which are available through the interface. The return is a JSON object consisting of key value pairs in which the key report IDs and the values are report names:

{
 "EAPage":"Pages",
 "CCOverview":"Overview",
 "72":"My individual Report",
 …
}

Report data can be called with the numerical or alphabetical report IDs.

Calling Report & Metadata

The queries of the etracker report REST API are structured as follows:

https://ws.etracker.com/api/v6/report/#ReportID#/#Service#

The available services are:

Querying Report Information

Calling the information and metadata of the report ‘Device’ is done with the following query: https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/info The return is a JSON array with one element and has the following structure:

{
 "report": {
 "createDate": "2016-01-01 00:00:00",
 "dimensions": "1",
 "segments": "0",
 "visualizationType": "",
 },
"attributes": [
 {
 "id": "device_type",
 "label": "Ger\u00e4tetyp",
 "type": "attribute",
 "sortable": true
 },
 …
 ],
"key-figures": [
 {
 "id": "unique_visits",
 "label": "Visits",
 "type": "integer",
 "sortable": true
 },
 …
 ]
 "views": [
 {
 "view_id": "24",
 "name": "Test Configuration",
 "tm": "1477324586",
 "access": "this_user",
 "is_default": false
 },
 …
}

The return object contains four sub-elements:

1. A report object with general information, like the date, where a report was generated.
2. An attribute array with metadata on each attribute in the report.
3. A key figures array with metadata on each key figure in the report.
4. A views array with metadata on each of the views of the report defined by the users.

The arrays for the attributes and key figures contain objects with the following data for each attribute and each key figure:

1. The id for the communication with the REST API.
2. A name legible for people (label). The language of the names depends on the account ID or sub-user ID used in the header and can be modified using the corresponding settings in the etracker application.
3. The data type (type) of the values in the column.
4. A Boolean value (‘true’ or ‘false’), which indicates if the report can be sorted by attribute or by key figure.

The data types which can be found in etracker reports are described in the following table. The sample data is data as it is returned from the REST API.

Views can be defined and saved by each user for each report interactively in the etracker application. The views array contains the following data on each view defined by the users.

1. The view_id for the communication with the REST API.
2. The unique name provided by the users (name).
3. Other metadata for the view (e.g. date of creation).

Calling Report Data

Calling the data of the ‘Device’ report is done using the following query (a data query without parameters is possible, but not recommended):

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/data?limit=10

This query returns data in JSON format. For CSV data, ‘data.csv’ instead of ‘data’ at the end of the URI is all that is needed. For the return format, however, CSV and JSON queries are identical. For this reason, we will only describe the JSON case in this section. The return data have approximately the following format:

[
    [
        "-,-,-,-,-,-,-,-,-,-",
        "=S",
        "",
        …
        "",
        104377,
        …
        4.58239668
    ],
    [
        "373563,1417345,1426710,1426574,1426574,1430935,1373563,1373563,0,3",
        "=0",
        "Desktop",
        …
        "no customer",
        34201
        …
        2.3541867
    ],
    ...
]

The return is a JSON array of maximum 11 arrays as the parameter limit was set as equal to 10. Each array represents a data record or a line in the return table. The first array is always the ‘Total’ line, in which the key figures were aggregated across all attribute value combinations. The other arrays are attribute value combinations with the corresponding aggregated key figures. Since no sorting information was provided in the parameters, the order of the lines does not matter.

Each line begins with a list of IDs of the attribute values which were used for the attribute value combination. Each attribute value has an ID which needs to be used if a specific attribute value is to be referenced via the REST API. The attribute value IDs for the same attribute values can vary from one etracker account to the next. Inside an account however they are always unique.

The second element in each line is a designation: ‘=S’ for the line, ‘Total’ and ‘=0’ for all other lines. The attribute values of the attribute combination follow in the same order as in the report information and then the key figure data of the key figures also follows in the same order as in the report information.

The above example is simply for introductory purposes and does not represent sensible use of the etracker REST API. To use the REST API in a sensible way, the desired data range and the order needs to be narrowed down using parameters.

Calling Query-specific Report Metadata

For each data query of a report, the corresponding query-specific metadata can be called. To see the metadata of the above query, ‘data’ just needs to be replaced with ‘metaData’. Here, the parameters should be kept intact.

https://ws.etracker.com/api/rest/v3/report/CCWRDeviceType/metaData?limit=10

This query returns a JSON array with one entry per column in the respective data query. The first two entries have the IDs ‘id’ and ‘tree_status’ and the type ‘null’. They correspond to the first two columns described above, which are neither attributes nor key figures.

[
 {
 "id": "id",
 "label": zero,
 "type": zero,
 "sortable": true
 },
 {
 "id": "tree_status",
 "label": zero,
 "type": zero,
 "sortable": true
 },
 {
 "id": "device_type",
 "label": "Ger\u00e4tetyp",
 "type": "attribute",
 "sortable": false
 },
 ...
]

Defining etracker Reports

The etracker reports can be understood as dynamic tables or as so-called data cubes. They consist of Attributes and Key Figures. In the literature, the terms Dimensions (for attributes) and Measurements (for key figures) are used.

Attributes contain nominal or categorical values which are not numbers and show the characteristics of user interactions. Typical attribute values are names (e.g. ‘Homepage’ or ‘Womenswear’), categories (e.g. ‘customer’, ‘not customer’) or times (e.g. ‘2021-01-25’ or ‘9 AM’). Some attribute values have a natural order (e.g. the times), but most cannot be sorted sensibly or just alphabetically. If one value should be selected from three attributes, then we talk of an attribute value combination or characteristic. If, for example, the attributes ‘Page name’, ‘Country’ and ‘Operating System’ are given, then the values ‘Homepage’, ‘Germany’ and ‘Windows’ would be an attribute value combination and ‘Homepage’, ‘Austria’, ‘Windows’ would be another attribute value combination.

Key figures contain numerical values which can be sorted and aggregated. Key figures are always returned from the REST API in aggregated form. The aggregation method depends on the key figure. The key figure ‘Bounce Rate’ is used for averaging. The key figure ‘Visitors’ however, is used for summing. Each query of a report via the REST API returns a table which returns a specific aggregated view. Each key figure is aggregated for each existing attribute value combination. Each line in the table then consists of one attribute value combination followed by the aggregated key figures which belong to it. Two lines of such a table could look like this:

The attribute value combination and key figures of the second line can be interpreted as follows: There were 57 visitors to the homepage from Austria using the Windows operating system and 35.09% of them viewed just one page.

Basic Parameters of the Report API

The following section describes the basic parameters of the Report API.

The following query uses the above parameters in order to proceed in a more targeted way when querying the ‘Devices’ report.

https://ws.etracker.com/api/v6/report/CCWRDeviceType/data?startDate=2021-01-01&endDate=2021-01-31&sortColumn=unique_visits&sortOrder=1&offset=0&limit=10

The parameters were set as follows:

• startDate = 2021-01-01
• endDate = 2021-01-31
• sortColumn = unique_visits (Besuche)
• sortOrder = 1 (absteigend)
• offset = 0
• limit = 10

This sorts the data recorded in January 2021 in descending order according to the ‘Visits’ key figure column and returns the first 10 lines together with the ‘Total’ line. In case additional data is desired, offset and limit can be increased progressively until no more data is returned. The next 10 data records for example were queried as follows:

https://ws.etracker.com/api/v6/report/32005/data?startDate=2021-01-01&endDate=2021-01-31&sortColumn=unique_visits&sortOrder=1&offset=10&limit=10