Skip to content

Public API

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 Customer Success 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.

OptiRTC recommends the use of https:// for all requests to Opti APIs and for all web pages that issue requests to Opti APIs. Opti currently supports TLS 1.2 to establish secure connections (scan and audit of the Public API's implementation of TLS provided by Qualys SSL Labs).

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.

Transformed DataStreams

Some DataStreams are transformations of others based on account configuration. For example, DataStreams about water elevation are often available in both "Local" (relative to the bottom of on-site storage) or another reference datum such as Mean Sea Level or NAVD88. These DataStreams are available via the Public API if the query string parameter includeTransforms=true is included in requests to the /api/DataStream endpoint, as discussed in the docs below. Please contact Opti Customer Success to change your reference datum.

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.

Authorization

You must include a key parameter in the query string of each request to the Opti Public API. Opti uses this key to authorize 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 Opti Customer Success.

Note

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.