Public API (1.0)

Download OpenAPI specification:Download

Overview

The Opti Public API provides a simple, read-only interface to access metadata and the last 3 days of real-time data points of all metrics in an Opti Platform Account:

  • Web developers can use the Public API to display real-time metrics from Opti facilities on their own websites - no backend database required.
  • Systems integrators can use the Public API to pull data into their own GIS or ETL systems, for example, to connect real-time stormwater conditions to their existing asset management software.
  • Analysts can use the Public API to pull data into their analysis scripts for repeated analysis.

To learn about how Opti's data-driven products are enhancing community resilience to heavy rainfall across North America, see the Opti Home Page.

Getting Started

To use the Opti Public API, you need an API key that grants access to the metrics from your Opti Account. Each API key provides access to a specific collection of metrics. Opti Support can provide authorized account administrators with the API keys you include in each request to the OptiRTC Public API. You will need one of these keys and the ability to make HTTP requests to use the OptiRTC Public API. See Authentication for more information.

Browse examples

OptiRTC provides simple examples of using open-source technologies to interact with the OptiRTC Public API. Find out more on our Github page.

Versioning

A versioning mechanism for future interfaces is in place. To request a particular version of any API response, change the value of the 'Accept' header in the HTTP request from 'application/json' to 'application/vhd.optirtc-v{version}+json', where {version} is an integer greater than 0. For example, to request the v1 representation you would set the 'Accept' header to 'application/vhd.optirtc-v1+json' for all of your requests. All requests with the 'Accept' header set to 'application/json' will return the latest available version.

DataStreams, DataPoints, DataValues, and Resources

All metrics on the Opti Platform - sensor feeds and derivative data products - are described by Resources. A Resource defines an immutable set of metadata about a metric. When a metric's metadata changes, such as when it is moved or renamed, a new Resource is created to describe the metric's values created after that change. Only one Resource describes a given metric's values at any moment in time.

Public API users access Resources via DataStreams. DataStreams provide a persistent identifier for all Resources that describe a metric over time. When metadata is updated and the Resource defining a metric changes, the DataStream will now include two Resource definitions. The Datastream endpoint will now return multiple entries with the same id, each with a different resourceId and validFrom date.

Public API users access metric values as DataPoints. A DataPoint is a collection of DataValues at a single point in time. A DataValue is a value and a Resource identifier, which can be matched to the 'resourceId' property of DataStream metadata to determine how to interpret individual DataValues.

The structure of the Opti Platform Public API enables consuming applications to access all metrics including sensor data, command targets, alarm status, and command transmission history from a single set of endpoints.

Cross origin requests

The OptiRTC Public API supports the WHATWG spec for Cross-Origin Resource Sharing (CORS). This technology allows Javascript clients to make AJAX requests against the OptiRTC Public HTTP API while being hosted in another internet domain. This capability enables real-time data visualizations on websites hosted outside of OptiRTC.

Authentication

apiKeyQuery

You must include a 'key' parameter in the query string of each request to the Opti Public API. Opti uses this key to authenticate and throttle all requests to the Public API to help provide reliable and rapid services to all of its customers.

API Keys can be acquired and replaced by contacting your Opti Support representative. If you are building multiple web sites, ETL workflows, or other applications on top of the Opti Public API, Opti recommends using a different API key for each application to avoid unnecessary throttling from occurring. All throttled requests will return an HTTP 429 status code.

Security Scheme Type API Key
Query parameter name: key

Datastream

Get all DataStreams associated with the passed in key. This endpoint implements server-side data paging to control the size of each response. Clients should check for the presence of a 'NextPageLink' property along with the response Items, indicating that there is more data to be returned for the original request. The 'at=X' query parameter is the UTC date to filter by. (yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ) The 'top=Y' query parameter will restrict the results to the top Y values. The 'skiptoken=Z' query parameter will tell the server to omit the first Z datastreams from the results.

Authorizations:
query Parameters
key
required
string

OptiRTC Public API key authorizing access to the DataStreams.

at
string

ISO-8601 Date String in UTC. (yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ); if omitted, server will interpret as “now”.

top
integer

Limit results to the first top ordered by Id.

skiptoken
integer

Paging parameter to return the page after this number of results.

Responses

Response samples

Content type
application/json
{
  • "Items":
    [
    ],
  • "Count": 10
}

DataPoint-Get-Range

Get a range of DataPoints of a particular DataStream bounded by time coordinates, DataPoint ids, and paging parameters. This endpoint implements server-side data paging to control the size of each response. Clients should check for the presence of a 'NextPageLink' property along with the response Items, indicating that there is more data to be returned for the original request. The example below shows the first page of a response assuming the page limit is set at 3 DataPoints per page and the request was for 5 DataPoints (top=5 in query string). See https://github.com/OptiRTC/OptiRTC-API-examples for examples using this endpoint.

Authorizations:
query Parameters
key
required
string

OptiRTC Public API key authorizing access to these DataPoint resources.

dataStreamId
required
integer

Id property of the DataStream to get DataPoints of. See the Datastream endpoint for the DataStreams this API key can access.

historicalId
string

Id property of the historical DataPoint, inclusive. This should have a bigger value than the modernId. Specifying 1 less than the id of the most-modern DataPoint you have received as the historicalId will return all DataPoints that have been created since you last requested DataPoints of this DataStream.

modernId
string

Id property of the modern DataPoint, inclusive. This should have a smaller value than the historicalId.

utcHistorical
string

Historical time boundary of datapoints to return. ISO-8601.

utcModern
string

Modern time boundary of datapoints to return. ISO-8601.

skiptoken
string

Paging parameter. Skip this many of the most-recent values, given other query string parameters.

top
integer

Paging parameter. Return this many of the most-recent values, given other query string parameters.

verbosity
string

Scope of data request. Either identity (default) or display. See /api/datapointverbosity/ for additional information.

unit
string

Abbreviation of the unit in which to return data. May be null, in which case the stored unit of the datastream will be used.

Responses

Response samples

Content type
application/json
{
  • "Items":
    [