What's next for the Clarity API?

Take a sneak peek at the changes in store for the Clarity API in 2023.

The Clarity API is evolving to make it more powerful and better serve you. In the last year, you’ve seen new v2 endpoints for better reporting on your devices (Nodes and accessory Modules) and their status. Next, we will be offering improved endpoints for Datasources and Measurements. 

This article is a friendly, early heads-up about changes that are in the works – not final – but where we want to keep you in the loop. If you are maintaining copies of Clarity identifiers in your own database, we want you to stay ahead of these changes. 

And a big thank you for all your feedback. Learning about how you are using the API is what helps us to make these improvements.

Datasources and Subscriptions

In v1 a datasourceId is an amalgamation of concepts that we want to distinguish going forward - and thus we needed to create new identifiers. The independent v2 concepts are: datasource, source and subscription, described below.  This significant change will enable the following, all coming in the future:

• Replace a failed device with a new one and have the timeline of measurements continue uninterrupted, across devices
• Re-deploy an existing device for a new monitoring purpose and have there be independent measurement timelines for each deployment
• Easily share a dataflow from a datasource with another organization 
• Easier renewals/extensions of subscriptions, independent of the current device that powers a datasource

To achieve these goals, we're bidding farewell to v1 datasources and introducing new v2 concepts:

1. Datasource - A dataflow, regardless of what equipment is generating that data
2. Source - The underlying origin of the measurement data, whether that be the current Clarity Node or the reference site that is generating the data
3. Subscription - The permission granted to an organization to access and view data flowing from a Datasource

Historical data

Accessing large data files of historical measurements is difficult because of the limitation that you can only pull a “page” of measurements at a time (a limited number of measurements for the synchronous API). We are working to build an alternative API for submitting a request for a file that can then be downloaded. This will eliminate the need to have incremental fetch-and-assemble of a large dataset.

Implications on endpoints

Because a datasource will be able to bridge measurements across original & replacement devices, there will be endpoints both for reporting measurements at the datasource level and for reporting measurements from just one underlying source (A specific Clarity Node or reference site).

/v1/measurements

In the Request:

code

datasourceId

org

average

skip and limit

aqi

In the Response:

_id

recId

average

/v1/datasources

In the Request:

org

In the Response:

datasourceId