API Guide
Oceans 3.0 API overview
Check here for more information.
Glossary of terms
Check here for more information.
The ONC class
The ONC class provides a wrapper for Oceans 3.0 API requests. All the client library’s functionality is provided as methods of this class. Each Oceans 3.0 public API has a corresponding public method in this class. In addition, the ONC class provides some useful helper methods that involve multiple APIs to simplify the workflow.
Create an ONC object to access this library’s functionalities.
from onc import ONC
onc = ONC("YOUR_TOKEN_HERE")
Discovery methods
Discovery methods can be used to search for available locations, deployments, device categories, devices, properties, and data products. They support numerous filters and might resemble an “advanced search” function for ONC data sources.
Use discovery methods to:
Obtain the identification codes required to use other API services.
Explore what’s available in a certain location or device.
Obtain the deployment dates for a device.
List available data products for download in a particular device or location.
Note
Locations can contain other locations.
“Cambridge bay” may contain separate children locations for its underwater network and shore station.
Locations can contain device categories, which contain devices, which contain properties.
Searches can be performed without considering the hierarchy mentioned above.
You can search for locations with data on a specific property or search for all properties in a specific location.
Method |
Description |
API Endpoint |
|---|---|---|
Returns locations |
||
Returns a location tree |
||
Returns a list of device deployments |
||
Returns a list of device categories |
||
Returns a list of devices |
||
Returns a list of properties |
||
Returns a list of data products |
Data product download methods
Data product download methods allow you to request and download more than 120 different types of ONC data products, with granular control over what data to obtain, from where, and in what time frame. They are comparable to the download functionality from ONC’s Data Search tool.
Examples of usage include:
Downloading PNG plots of sensor readings in a device
Downloading sensor readings as .mat files, text files, or in commercial manufacturer formats
Downloading compressed or raw audio files from hydrophones
Note
If the data product requested doesn’t exist in our archive, it will be generated by our servers before your download starts.
Method |
Description |
API Endpoint |
|---|---|---|
Request a data product |
||
Check status of a |
||
Run a requested data product |
||
Cancel a running data product |
||
Restart a cancelled data product |
||
Download a data product |
Helper methods are listed below.
Method |
Description |
|---|---|
Request, run, and download a data product |
Near real-time data access methods
Near real-time (as fast as they get into our database) data access methods allow the extraction of sensor data as time-series, either as processed scalar data with Quality Assurance and Control flags (QAQC) or directly as raw data obtained from the device in its specific output format. In contrast to the Data product download methods, this data can be downloaded directly without waiting for any kind of generation process.
Common use cases include:
Plotting time series from properties in a specific time frame or in “near real-time”
Quickly obtaining the latest reading from a particular sensor
Obtaining raw unprocessed data from our instruments (data might require processing to be readable)
Note
The methods getDirectByLocation() and getDirectRawByLocation() obtain data readings from a location
no matter what device it came from (hence the need to specify a device category code instead of a single device code).
You might want to obtain data by location instead of by device, as individual devices are often replaced/repositioned.
Each request to our API can return a maximum of 100,000 samples; larger data requests must be downloaded as a sequence of pages. Use the allPages parameter to automatically download all pages required for your requested time frame.
Method |
Description |
API Endpoint |
|---|---|---|
Returns scalar data |
||
Returns scalar data from a specific device |
||
Returns raw data |
||
Returns raw data from a specific device |
Helper methods are listed below.
Method |
Description |
|---|---|
Returns a list of sensor category codes |
Archive file download methods
These methods allow users to directly download previously generated data product files from our archive.
ONC systems auto-generate and archive files of different types at set time intervals. These archived files can be downloaded without waiting for a generation process to finish (potentially faster than Data product download methods).
Note
Archived files have a unique filename (e.g. “NAXYS_HYD_007_20091231T235919.476Z-spect.png”) that includes the device code (“NAXYS_HYD_007”) and the UTC date-time when the data in the file started being measured (“20091231T235919.476Z”). The filename might contain additional information.
Caution
Due to security regulations, some very recent files (e.g. hydrophone.wav files in the last hour) might not be made immediately available.
Method |
Description |
API Endpoint |
|---|---|---|
Returns a list of available archive files |
||
Returns a list of available archive files |
||
Download an archive file |
Helper methods are listed below.
Method |
Description |
|---|---|
Download a list of archived files that match the filters provided |