Data Analytics API (REST API)

Access Data Analytics widgets underlying data via API

For every Data Analytics widget, the underlying data can be queried via a provided REST API. Integration to third-party applications works out fast and easy.

The REST API makes generated event data available to third-party applications, retrieved from your Data Analytics widgets.

API Call

Once you configure a widget, find the item "API call" in the side menu.

The "API Call" option is available for every widget

The provided dialog pop up shows detailed information on how the API request for the generated data of this particular widget looks like. Copy/paste the curl command into a terminal and execute it. You can directly test the call within the dialog, including the response format, by clicking on "Try it out!" which does not require the usage of a terminal.

The specific API request is ready to use.

The provided access token is temporary. For a permanent integration into third-party applications, please request a permanent access token via the Support Portal.

Authentication

We strictly follow the OAuth flow documented by Microsoft. There are several client libraries that you can use.

Integration example

In the GitHub repository below you can find example code that highlights how to integrate the data into your own application. It showcases how to handle the required authentication as well as how to perform queries.

GitHub - hal9000-swarm/analytics-integration-example: Example of integrating the Swarm data analytics APIGitHub

Example Request

Bicycle Counting

You can see a Data Analytics widget for bicycle counting as an example below. The respective type of widget (Traffic Counting) is selected, data is aggregated per day, split by object class and direction, and we filter for bicycles only.

Example widget for bicycle counting

API Request

The API-Call option shows the respective GET request for this data, as you can see below.

https://example.com/cubejs-api/v1/load?query=
{
   "measures":[
      "CrossingEvents.count"
   ],
   "dimensions":[
      "CrossingEvents.classification",
      "CrossingEvents.direction"
   ],
   "segments":[],
   "filters":[
      {
         "member":"CrossingEvents.streamId",
         "operator":"equals",
         "values":[
            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
         ]
      },
      {
         "member":"CrossingEvents.classification",
         "operator":"contains",
         "values":[
            "bicycle"
         ]
      },
      {
         "member":"CrossingEvents.lineId",
         "operator":"equals",
         "values":[
            "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
         ]
      }
   ],
   "timeDimensions":[
      {
         "dimension":"CrossingEvents.timestamp",
         "granularity":"day",
         "dateRange":"This week"
      }
   ],
   "order":{}
}

API Response (shortened)

{
  "queryType": "regularQuery",
  "results": [
    {
      "query": {...},
      "data": [
        {
          "CrossingEvents.classification": "bicycle",
          "CrossingEvents.direction": "in",
          "CrossingEvents.timestamp.day": "2021-11-02T00:00:00.000",
          "CrossingEvents.timestamp": "2021-11-02T00:00:00.000",
          "CrossingEvents.count": "235"
        },
        {
          "CrossingEvents.classification": "bicycle",
          "CrossingEvents.direction": "out",
          "CrossingEvents.timestamp.day": "2021-11-02T00:00:00.000",
          "CrossingEvents.timestamp": "2021-11-02T00:00:00.000",
          "CrossingEvents.count": "234"
        },
        {
          "CrossingEvents.classification": "bicycle",
          "CrossingEvents.direction": "in",
          "CrossingEvents.timestamp.day": "2021-11-03T00:00:00.000",
          "CrossingEvents.timestamp": "2021-11-03T00:00:00.000",
          "CrossingEvents.count": "203"
        },
        {
          "CrossingEvents.classification": "bicycle",
          "CrossingEvents.direction": "out",
          "CrossingEvents.timestamp.day": "2021-11-03T00:00:00.000",
          "CrossingEvents.timestamp": "2021-11-03T00:00:00.000",
          "CrossingEvents.count": "249"
        }
      ],
      "annotation": {...}
    }
  ],
  "pivotQuery": {...}
}

Extended Documentation

The REST API is based on Cube.js. More information on the functionality of the API can be found in the external documentation.