Extracting data from reports using the Digital Analytics API

Overview

The API conforms to REST architecture

Generate API URLs by using the Digital Analytics API window

You can configure API queries in several different formats for all standard reports in Digital Analytics. Choose from standard date ranges, including daily, weekly, monthly, quarterly, and yearly. You can also specify an optional second date range for comparison.

You can use the Digital Analytics API window in the Manage section of the side navigation pane to configure API queries for all standard reports.

📘
Note:
For configuring API URLs for trended Top Line Metrics reports, see Return trended results for Top Line Metrics reports.

Click Manage > Distribution > API in the side navigation pane.
Use the lists to select a report category, format, report, view, and language. The available reports vary depending upon the category you choose.
Specify one of the standard date range types (daily, weekly, monthly, quarterly, or yearly) for Period A and optionally Period B.
The maximum amount of data that a digital Analytics API call returns vary by period type. You can circumvent these limits by making multiple calls to the API with different dates.
The following list shows the maximum number of periods that are returned per API call for each period type.

Daily: 93
Weekly: 52
Monthly: 60
Quarterly: 20
Yearly: 5

Use the calendars to specify the dates.
Click Generate API URL and Copy to Clipboard. Digital Analytics generates the URL and displays it in the text box.

Change the query by manually modifying the URL

After you generate an API URL, you can manually modify it to change the query. For example, you can change the date range in the URL to a different time period. In this way, you can reuse or update an API call without logging in to Digital Analytics.

Use the correct syntax when you configure Digital Analytics API URLS manually.

📘
Note:
Trended Top Line Metrics reports can include more parameters. For more information, see Return trended results for Top Line Metrics reports.

The following example shows the basic API URL structure: https://welcome.coremetrics.com/analyticswebapp/api/1.0/

📘
Note:
Use the appropriate Acoustic Digital Analytics service domain name for your organization.

The basic structure is followed by these elements:

Data type
Report name
clientId (production client ID)
username (your user ID)
format (file format for the returned data)
userAuthKey (user authentication key)
language (language and locale)
viewID (report view)
period_a, period_b (period date range)
The user authorization key is automatically generated by the API when you use the API window to generate the URL.

The period date range is the end day of the range, prefixed by a period type designation (D=daily, W=weekly, M=monthly, Q=quarterly, Y=yearly).

The following example API URL requests data in XLS format from the Top Products report for March 28, 2013.

📘
Note:
The URL shown here is broken into multiple lines for readability. The actual URL does not contain line breaks. Use the appropriate Acoustic Digital Analytics service domain name for your organization.

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
report-data/topbrowsedproducts.ftl?clientId=11111111&[email protected]
&format=XLS&userAuthKey=7177773b-1e99-40d7-866f-d52556be60a0
&language=en_US&viewID=default.ftl&period_a=D20130328

(Optional) Return reports that exceed the API row limit

To perform optimally and meet format requirements, Digital Analytics API calls return a maximum of 20,000 rows for a single report. To return more than 20,000 rows, you can create a script that submits the API request multiple times until the full report is returned.

Create a script using the following HTTP request syntax:

GET http://[api-url]?[parameters] HTTP/1.1
Accept-Language: en-US
Host: www.hostname.com

For each subsequent request in your script, add the startRow parameter to return the next 20,000 rows. For rows 20,001 - 40,000, add startRow=20001 to the request.
Construct the script to manage pagination by looping through 20,000 results at a time. Your code must check the row count in the returned rows and add it to a global counter. When any request returns less than 20,000 rows, exit the loop.

Return trended results for Top Line Metrics reports

Trended Top Line Metrics reports offer more options. However, you can access trended Top Line Metrics data only by manually configuring an API URL, or by modifying a previously generated URL.

You can configure an API URL to return trended results for the Top Line Metrics report. The trended results are summed by day.

📘
Note
You must configure a trended Top Line Metrics API URL manually, either by creating a URL or modifying a previously generated URL. You cannot use the API window in Digital Analytics to create a trended Top Line Metrics API URL.

The following steps provide an overview of the procedure for returning trended Top Line Metrics results:

Obtain a user authentication key for your user account.
Before you can configure a Digital Analytics API URL for a trended Top Line Metrics report, you must submit a request for a user authentication key. After the API returns the authentication key, you can add the key value to the userAuthKey parameter in your API URL.
a. Modify the following URL to include your user account information: client ID, user name, and password.

📘
Note:
The URL shown here is broken into multiple lines for readability. The actual URL does not contain line breaks. Use the appropriate Acoustic Digital Analytics service domain name for your organization.

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
userAuthorizationKey?clientId=client_id
&username=username&password=production-password&format=json

b. Paste the URL into your web browser and press Enter.The Digital Analytics API returns an authentication key for your user ID.
2. Add the authentication key to your API URL.
3. Choose one of the following options for configuring the URL:

Specify a standard or custom date range by adding a start date and an end date to the URL.
Specify the date range for a trended Top Line Metrics API call by including a start date and an end date in the URL. If the standard fiscal date ranges do not meet your needs, you can specify a custom date range.

📘
Note:
The URL shown here is broken into multiple lines for readability. The actual URL does not contain line breaks. Use the appropriate Acoustic Digital Analytics service domain name for your organization.

a. Add parameter values to a basic trended Top Line Metrics API URL. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id
&username=username&userAuthKey=API_Token&language=Language
&viewID=View_Name.ftl

b. Add the start_date_id, end_date_id, and period parameters to the URL and specify values. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id&username=user_id
&format=file_format&userAuthKey=API_Token&language=Language
&viewID=View_Name.ftl&startdate=start_date_id
&enddate=end_date_id&period=period_type

The start_date_id and end_date_id parameters accept an eight-digit numeric string in the format yyyymmdd. For periods other than daily, the start_date_id and end_date_id do not need to be the start and end dates of the period; the period within which the date falls is assumed.

For the period parameter, specify a daily, weekly, monthly, quarterly, or yearly period.

Request a report for one or more specific metrics.
You can submit an API call to return trended Top Line Metrics results for one or more specific metrics.

📘
Note:
The URL shown here is broken into multiple lines for readability. The actual URL does not contain line breaks. Use the appropriate Acoustic Digital Analytics service domain name for your organization.

a. Add parameter values to a basic trended Top Line Metrics API URL. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id
&username=username&userAuthKey=API_Token&language=Language
&viewID=View_Name.ftl

For information about the parameters, see the Basic syntax for Digital Analytics API URLs.

b. Add the metrics parameter to the URL and specify one or more metric IDs from the list of available Top Line metrics. Separate multiple metric IDs with commas. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id&username=user_id
&format=file_format&userAuthKey=API_Token&language=Language
&viewID=View_Name.ftl&metrics=Metric_ID

Specify a period start date to look forward or backward.

You can configure a trended Top Line Metrics API URL to look forward or backward from a specified date. For example, you can specify a date from last week and return results for the previous 10 weeks. You can also request a date from several weeks ago and return results from that date to the present.

You can request a single daily, weekly, or monthly time period.

📘
Note:
The URL shown here is broken into multiple lines for readability. The actual URL does not contain line breaks. Use the appropriate Acoustic Digital Analytics service domain name for your organization.

a. Add parameter values to a basic trended Top Line Metrics API URL. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id
&username=username&userAuthKey=API_Token&language=Language
&viewID=View_Name.ftl

b. Specify a date, direction, and number of periods to look forward or backward. Use the following syntax:

https://welcome.coremetrics.com/analyticswebapp/api/1.0/
toplinetrend-data/topline.ftl?clientId=client_id&username=user_id
&format=file_format&userAuthKey=API_Token&language=Language&viewID=view_name.ftl
&period_a=period_type+DATE_ID&direction=direction&numPeriods=number_of_periods

where:

period_a
Identifies the date (in yyyymmdd format) and period type from which you want to go forward or backward. Preface the date with the period type: d for daily, w for weekly, or m for monthly. For example, period_a=w20130301 is the week of March 1, 2013.
direction=
Identifies the direction to return data from the start date. Specify forward or backward.
numPeriods=
Identifies the number of periods to look forward or backward.

List of Top Line Metrics

You can use any of the following Top Line metrics in API calls.

ANONYMOUS_ORDERS
ANONYMOUS_PAGE_VIEWS
AVERAGE_TIME_PER_PAGE
AVG_NEW_SESSION_LENGTH
AVG_REPEAT_SESSION_LENGTH
BOUNCE_RATE
CART_ITEMS_ORDERED
CNT_CONVEVENTS
CNT_CUSTOMEVENTS
CNT_ELEMENTS
CNT_LINKIMPR
CNT_SHOPACT
DLOAD_NEW_SESSIONS
DLOAD_REPEAT_SESSIONS
DLOAD_SESSIONS
ELEMENT_VIEWS_PER_SESSION
ELEMENT_VIEWS
EST_ANONYMOUS_BUYERS
EST_ANONYMOUS_SESSIONS
EST_ANONYMOUS_VISITORS
EVENT_POINTS_PER_SESSION
EVENT_POINTS_PER_VISITOR
EVENT_POINTS
EVENTS_COMPLETED
EVENTS_PER_SESSION
EVENTS_PER_VISITOR
ITEMS_ABANDONED
ITEMS_CARTED
NEW_BUYERS_PCT
NEW_BUYERS_PER_NEW_VISITOR
NEW_BUYERS
NEW_REGISTRANTS
NEW_SESSIONS
NEW_VISITOR_PCT
NEW_VISITORS
ONSITE_SEARCHES
ORDERED_CARTS
ORDERS_PER_SESSION
ORDERS
PAGE_VIEWS_PER_SESSION
PAGE_VIEWS
REFERRAL_NEW_SESSIONS
REFERRAL_REPEAT_SESSIONS
REFERRAL_SESSIONS
REPEAT_BUYERS_PCT
REPEAT_BUYERS_PER_REPEAT_VISITOR
REPEAT_BUYERS
REPEAT_REGISTRANTS
REPEAT_SESSIONS
REPEAT_VISITORS
SEARCH_NEW_SESSIONS
SEARCH_REPEAT_SESSIONS
SEARCH_SESSIONS
SERVER_CALLS
SESSIONS_PER_VISITOR
SESSIONS
TL_AVERAGE_SESSION_LENGTH
TL_BUYERS_PER_VISITOR
TL_ITEM_ABANDONMENT_RATE
TL_ORDERS_PER_VISITOR
TL_TOTAL_BUYERS
TL_TOTAL_ORDERS
TL_TOTAL_PAGE_VIEWS
TL_TOTAL_SESSIONS
TL_TOTAL_SHOPPING_CARTS
TL_TOTAL_VISITORS
UNIQUE_BUYERS
UNIQUE_REGISTRANTS
UNIQUE_VISITORS
US_SESSIONS_PCT

Commerce metrics
CART_ABANDONMENT_RATE
ORDERS_PER_SESSION
TL_AVERAGE_ORDER_VALUE
TL_BUYERS_PER_VISITOR
TL_ITEMS_PER_ORDER
TL_TOTAL_ITEMS_ORDERED
TL_TOTAL_ORDERS
TL_TOTAL_PRODUCT_VIEWS
TL_TOTAL_SALES

Event metrics
EVENTS_COMPLETED
EVENTS_PER_SESSION
EVENT_POINTS
EVENT_POINTS_PER_SESSION

Visitor Metrics
TL_TOTAL_BUYERS
TL_TOTAL_VISITORS
UNIQUE_REGISTRANTS

Acquisition Metrics
NEW_BUYERS
NEW_BUYERS_PCT
NEW_SESSIONS
NEW_VISITOR_PCT
NEW_VISITORS

Retention Metrics
REPEAT_BUYERS
REPEAT_BUYERS_PCT
REPEAT_SESSIONS
REPEAT_VISITOR_PCT
REPEAT_VISITORS

Activity Metrics
AVERAGE_TIME_PER_PAGE
BOUNCE_RATE
ELEMENT_VIEWS_PER_SESSION
ELEMENT_VIEWS
ONSITE_SEARCHES
PAGE_VIEWS_PER_SESSION
SERVER_CALLS
SESSIONS_PER_VISITOR
TL_AVERAGE_SESSION_LENGTH
TL_TOTAL_PAGE_VIEWS
TL_TOTAL_SESSIONS

Expected outcomes

The API can return reports in four formats: XLS, CSV, XML, and JSON.

XLS
Microsoft Excel format. The report file is named download.xls.
CSV
Comma-separated value format. The report file is named download.csv.
XML
A web page with XML-formatted data that displays in a browser.
JSON
A web page with JSON-formatted data that displays in a browser.