Aggregation API

Watershed receives data from various data sources via xAPI, aggregates that data and then displays it in insightful reports and visualizations. Sometimes clients want to make use of that aggregated data outside of Watershed. This guide explains how.

The Aggregation API allows you to fetch aggregated data from Watershed where there is not an existing card to aggregate this data. Like card data, Aggregation API data is cached to avoid performance issues relating to multiple requests for the same data.

This guide consists of 2 sections:

API

This section outlines the allowed resources and methods of the Aggregation API. In order to interact with the Aggregation API, you will need authentication credentials and an organization id (org id).

Get aggregated data as a csv

Request URL: /api/organizations/[org-id]/aggregation/csv

Method: GET

Expected response code: 200 OK

Request parameters

Parameter

Details

config

A configuration object with filter, dimension and measure properties, much like the advanced configuration of a leaderboard card. The dimension defines the rows of the aggregated data whilst the measures define the columns.

name

The name of the csv file Watershed will return.

Response

A successful response will return a csv file containing the requested data. The first row of this file after the headers will contain an average for each measure.

Please note: currently it is only possible to fetch data in csv format. We may add additional format options such as JSON in future releases. Let us know if that’s a feature you would use!

Example

For readability, line breaks have been added to the request url below.

GET https://sandbox.watershedlrs.com/api/organizations/3093/aggregation/csv?
config={
  "filter":{"activityIds":{"ids":["https://example.com/some-activity"],"regExp":false},"personIds":null,"groupIds":null,"dateFilter":null},
  "dimensions":[{"type":"STATEMENT_PROPERTY","statementProperty":"actor.person.id"}],
  "measures":[{"name":"Interaction Count","valueProducer":{"statementProperty":"id","type":"STATEMENT_PROPERTY"},"aggregation":{"type":"COUNT"}}]
}
&name=file.csv

This returns a csv file with the following structure:

Activity,Interaction Count
Average,3
Joe Bloggs, 5
Jane Doe, 1

Using a leaderboard card to create the configuration object

One way to create the configuration object for use with Aggregation API requests is to create a Leaderboard card that generate the data you require and then copy the configuration from that. To do this you should:

  1. Create and save a Leaderboard card displaying the data you want.
  2. Copy the Leaderboard's configuration by configuring the card then choosing Advanced configuration.
  3. For each measure, delete the id and fingerprint properties. 

Please note: you will need to ensure that each measure includes the full configuration for that measure, not just the measure name and id. Saving and re-editting the card normally causes the full measure configuration to be pulled in to the card configuration.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.