The Oceans 3.0 API provides programmatic access to the over 500 terabytes of data collected since 2006, from thousands of sensors, through a collection of web services. This Guide describes how to use the Ocean 3.0 API to write scripts in any language that supports HTTP requests, or use our sample code or one of our client libraries to shortcut the development process.
General Overview
The Oceans 3.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 five 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 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.
- 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 three services that return data defined by filter criteria. The data delivery services are split into two functional groups based on their delivery method: a) Asynchronous 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 are available in the Oceans 3.0 Data Search web application. Data Products can be requested from instruments in five different ways, to suit 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, sub-sampling, 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.
Quick Start
If you are a Python, MATLAB or R programmer, you can quickly start using the Oceans 3.0 API, by taking advantage of our client libraries. This guide will take you step-by-step through getting setup, writing code and retrieving data.
1. Choose your Language
- All code samples and client libraries are available in Python, MATLAB and R; however, any programming language that can make HTTP GET requests can be used, along with the API Reference to make requests and download data using the ONC web services.
3. Discover your Data
- Use the Discovery services to find your data
- Use the getLocations() function to find locations by code, name, device category, device, data product and deployment date range.
- Use the getDevices() function to find devices by code, name, location, device category, property data product and deployment date range.
- Use the getDeployments() function to find device deployments by location code, device code, device category code, property code and deployment date range.
- Use the getDeviceCategories() function to find device categories by code, name, description, location, device and property.
- Use the getProperties() function to find properties by code, name, description, location, device category and device.
- Use the getDataProducts() function to find data products and extensions, by code, extension, name, location, device category, device and property.
- Use the following pages for valid codes that can be used as filters in both the discovery and delivery services
- Use the Discovery services to find your data
4. Download your Data
- Decide how you want to retrieve your data
- Do you want a data product?
- If so, use the orderDataProduct() function
- Figure out what data product options to include using the Data Products documentation
- Pass the filter criteria identified in #3 into the function
- For Site Device data request include locationCode and deviceCategoryCode
- For Primary Sensor level data request include locationCode and propertyCode
- For Sensor Level data request include locationCode, deviceCategoryCode and propertyCode
- For Device (all properties) data request use deviceCode
- For Device Property data request use deviceCode and deviceCategoryCode
- Include dateFrom and dateTo
- Include dataProductCode, extension and appropriate data product options
- If so, use the orderDataProduct() function
- Do you want a data product?
- Decide how you want to retrieve your data
- Do you want a small amount of scalar data in near real-time?
- if so, use the getDirectScalar() function
- Pass the filter criteria identified in #3 into the function
- Include locationCode, deviceCategoryCode
- Include dateFrom and dateTo
- Pass the filter criteria identified in #3 into the function
- if so, use the getDirectScalar() function
- Do you want a small amount of scalar data in near real-time?
- Do you want to raw data directly from the instrument?
- if so, use the getDirectRaw() function
- Pass the filter criteria identified in #3 into the function
- Include locationCode, deviceCategoryCode
- Include dateFrom and dateTo
- Do you want to raw data directly from the instrument?
- Execute a data request.
- Do something with the results.
- Execute a data request.
For more information about getting started, see our API_Sandbox_Demo_August_2018public.pdf
Sample Code
Client Libraries (Deprecated)
Client libraries provide quick, easy and consistent access to Oceans 3.0 API, in popular scientific programming languages.
These libraries provide a class with methods that wrap web service calls, complex workflows, and business logic so that users can discover and download data (raw, text, image, audio, video or any other available) in a single line of code.
They are all free projects, published under Open Source licenses:
Language | Latest library version | Repository | License | Code Repository + documentation + examples | |
---|---|---|---|---|---|
Python | 2.3.5 (12/12/2019) | PyPI | Apache 2 | python-client (20/03/2024) | |
MATLAB |
| File Exchange | BSD 2 | matlab-client | |
R |
| Github | MIT | r-client |
If this is your first time using these client libraries, we suggest you visit the Installation and Getting started pages.
The latest library version works with the current version of Oceans 3.0 Web API.
New versions are created to resolve known client library issues, add new functionality or handle changes to the underlying Web Services.
Please report all issues with the web services, documentation, samples and client libraries by going to Oceans 3.0 Data Portal and clicking Request Support button available for each application.