Overview

Skill Level: Any

Step-by-step

  1. 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 step 3.

    1. Click Manage > Distribution > API in the side navigation pane.
    2. Use the lists to select a report category, format, report, view, and language. The available reports vary depending upon the category you choose.
    3. 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 aDigital Analytics API call returns varies 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

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

     

  2. 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 step 3.

    The following example shows the basic API URL structure.

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

    https://welcome.coremetrics.com/analyticswebapp/api/1.0/

    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 IBM Digital Analytics service domain name for your organization.

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

     

     
  3. (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.

    1. 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
    2. 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.
    3. 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.
  4. 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:

    1. 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.

      1. 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 IBM 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
      2. 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 IBM Digital Analytics service domain name for your organization.

        1. 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 Step 2.

        2. 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 IBM Digital Analytics service domain name for your organization.

        1. 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 Basic syntax for Digital Analytics API URLs.

        2. 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 IBM Digital Analytics service domain name for your organization.

        1. 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 parameters, see Step 1.

        2. 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:

          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 outcome

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.

 

Join The Discussion

Your email address will not be published. Required fields are marked *