Analytics API Reference

Introduction

Studio and Product Hub has built-in logic for posting responses and fetching results and reports. However in the case of reading reports outside of our tools, we've made available an API for them to be consumed.

API usage

If you need to fetch the response results outside of Ease Live Studio, you can use the following API:

• API Base URL: https://analytics.api.easelive.tv/api/v1

Reports

Fetch live response results with event data tied in with the response numbers. This endpoint is useful if you want to display a visual report in a backend andl only use one API request to fetch it all.

GET /responses/<accountId>/<projectId>/<programId>/report

Required:

• accountId → This is the name of your Ease Live account. It will always stay the same.
• projectId → Project ID
• programId → Program ID

Headers:

• Authorization → Bearer <token>

The endpoint is behind authentication. To log in, generate an API token on your Ease Live Profile page and login to get a token.

Example result:

{
  "accountId": "tutorials",
  "projectId": "7210eeba-d7f7-4428-a40d-6b52d11a9aa5",
  "programId": "14e8fe9c-bce4-4322-8aee-efc86cc415d1",
  "responses": [
    {
      "measureName": "quizResponse",
      "programId": "14e8fe9c-bce4-4322-8aee-efc86cc415d1",
      "contextId": "7fc9f3d3-20bb-484e-a330-91603beb4c1c", // This is the Program Event ID
      "options": [
        {
          "measureValue": 0,
          "total": 2,
          "label": "Stockton's career assists"
        },
        {
          "measureValue": 1,
          "total": 1,
          "label": "Wilt's minutes per game"
        },
        {
          "measureValue": 2,
          "total": 3,
          "label": "Jordan's points per game"
        },
        {
          "measureValue": 3,
          "total": 1,
          "label" "Sheed's techs in a season"
        }
      ],
      "total": 7,
      "title": "What is the most unbeatable record in the NBA?",
      "impressions": {
        "measureName": "quizImpression",
        "total": 7,
        "uniques": 7,
        "sessions": 12
      }
    }
  ]
}

Live results

Fetch live response results for a specific responseName on an accountId. This is the endpoint that is consumed by end-users running Studio UIs on their devices.

GET /responses/<accountId>/<responseName>/results

Required:

• accountId → This is the name of your Ease Live account. It will always stay the same.
• responseName → The response action name you've given the Response data source. If you haven't specified one, it's going to be a camelCased version of Response name.

Optional:

• projectId → Limit the results to a single project only
• programId → Limit the results to a single program only
• contextId → Limit the results to a single context only, like an event

Example:

The poll results from the Ease Live Play example above can be fetched using this exact API.

Results that are exposed to the end-users can be accessed without authentication headers, and are cached on a 5 second basis on the CDN.

https://analytics.api.easelive.tv/api/v1/responses/tutorials/pollResponse/results?projectId=9e304084-34ad-4c18-a867-f0e30de3ec10&contextId=80210657-c904-460a-b33f-7d6dda373826

Result:

{
  "accountId": "tutorials",
  "projectId": "9e304084-34ad-4c18-a867-f0e30de3ec10",
  "contextId": "80210657-c904-460a-b33f-7d6dda373826",
  "measureName": "pollResponse",
  "results": {
    "0": 1,
    "1": 2,
    "2": 1,
    "3": 1
  },
  "total": 4
}

The results object will return a list of indexes from the array list defined in Studio and Cockpit. Each index represents the numbers of answers given. total represents the summary of all answers.