The Oceans 2.0 API provides a collection of web services for programmatically unlocking access to the vast ONC data archive, whether it is scalar data, complex data or video and imagery. The services in the API are split into three functional groups: 1) Discovery, 2) Delivery and 3) Interoperability.
1) The discovery services are a collection of 5 services which are used to obtain all of the codes needed to successfully request data from the ONC data archive. The discovery services use reductive filtering to return a list, in json format of all of the items that meet a filter criteria defined as parameters in the request url. The services are designed to allow the codes returned from one service request, to be used for filtering in another. Because the names of the fields returned in the results match the names of the filters, it is easy to programmatically chain service requests together, for example, a deviceCategoryCode returned from the deviceCategories service can be used as a filter on the locations service to find all locations that have instruments of that device category, and finally, the locationCode and deviceCategoryCode can be used to request a data product from the dataProductDelivery service.
2) The data product delivery services are a collection of 3 services that return data defined by a filter criteria. The data delivery services are split into two functional groups based on their delivery method: a) Asyncrhonous for large volumes or resampled data and b) Synchronous for simple, near real-time scalar and raw data.
a) The asynchronous approach is handled by the dataProductsDelivery web service, which provides programmatic and url access to all the same data and data products as is available in the Oceans 2.0 Data Search web application. Data Products can be requested from instruments in 5 different ways, to suite different user workflows: by location and device category, by location, device category and property, by location and property, by device and by device and property. Because it is built on top of the Data Products framework, whenever new data products are made available or existing data products are improved, they are automatically made be available through the API. All of the same data product functionality, including quality control, subsampling, multiple file formats and more, can be requested through the API. With a new JSON data product, 'Time Series Scalar Data' products can be easily ingested into a program, in your programming language of choice, for further processing and analysis.
b) The synchronous approach is currently being handled by the scalardata and rawdata services. The objective of these services is to provide fast access to small amounts of simple data, such as the last reading from an instrument and return it immediately in the response payload in json format, so that it can be quickly utilized by the calling program. Because they are optimized for performance, the data can not be resampled or filtered in any way, and can only return a maximum of 100,000 records in the response.
3) The interoperability services consist of a) a Sensor Observation Service (SOS) and b) a collection of dataset services provided by an implementation of the OPeNDAP server, ERDDAP.
a) The SOS service provides access to ONC's archive of scalar data via the same locations (features of interest) and properties (observed properties) that the discovery services provide. Service has three methods for interacting with ONC scalar data archive: the GetCapabilities method for retrieving a list of the service offerings and metadata, the DescribeSensor method for detailed information about the sensors and processes generating the measurements and the GetObservatoin method for retrieving sensor observations and measurement data via a spatio-temporal query that can be filtered by phenomena.
b) The ERDDAP server provides tabledap datasets for access to complex data from ONC instruments such as ADCPs and Profiling systems (CTD, Fluorometer and Oxygen). The datasets are currently limited to a selected set of deployments in Barkley Canyon, Cascadia Basin, Endeavour, Folger Passage, Saanich Inlet and Strait of Georgia.
The Oceans 2.0 Wiki includes an API Reference and a comprehensive collection of code examples, snippets and use case scenarios, in multiple languages (Python, MatLab & R) to help the ONC developer community build powerful and useful tools to access the data they need to perform research and present the findings to help policy makers make effective decisions.
