The OOI Machine-to-Machine (M2M) interface provides programmatic access to OOI data via a RESTful Application Programming Interface (API). This interface allows authenticated users to request small amounts of data via synchronous JSON requests, request larger amounts of data in NetCDF or CSV format in order to download multiple data streams or data from multiple platforms, or set up recurring downloads to procedurally update an existing dataset. Additional commands allow for searches of the asset management system to find deployment, calibration, quality control (QC) parameters, annotations, and other information, both in bulk and for specific instruments or platforms.
OOI Machine to Machine (M2M) Examples
Full documentation of the M2M system is underway, but there are several existing “Community Tools” resources to assist in getting started using the API. The examples below are not comprehensive, but they include some step-by-step instructions and sample code that can be modified to request the data you are interested in. We recommend familiarizing yourself with OOI terminology and data structure using the OOI Knowledge Base and the additional resources at the bottom of this page before you dive into the M2M system.
The following examples show how the OOI API interface can be used to request, download and plot data from the OOI using various programming libraries.
The following Python notebooks demonstrate how the python requests library can be used to access data from the OOI M2M web service.
For additional guidance, please see the following examples, developed for the 2018 Early Career Data Workshops held at Rutgers University.
- Introduction to the OOI M2M Interface (aka the API)
- Synchronous Requests & Basic Plotting
- Example 1 – Requesting OOI Data in NetCDF Format – Demonstrates how the OOI M2M interface can be used to retrieve information about the instruments in the OOI database and request downloadable files for an instrument.
- Example 2 – Plotting OOI Time Series Data (from NetCDF files) – Shows how to programmatically download and work with NetCDF time series data from the OOI.
- Example 3 – Plotting DO Profiles (and more) from NetCDF data files – Demonstrates how to programmatically download and plot colored depth profilers using OOI NetCDF data, using data from the Cabled Array Oregon Slope Base Shallow Profiler Mooring Shallow Profiler CTD.
M2M User Login Information
Before you can use the OOI M2M Interface/API, you need to have an account on the OOI Data Portal. Please use the following steps to setup your account and retrieve your API Username and Token. (Note, these are different from the username and password you use to log into the Data Portal.)
- Create a user account on ooinet.oceanobservatories.org, or use the CILogon button with an academic or Google account.
- Log in
- Navigate to the drop down menu screen in the top-right corner menu
- Click on the “User Profile” element of the drop down.
- Copy and save the following data from the user profile: API Username and API Token.
Tools to access OOI M2M Web Services
Here is a quick rundown on how to access the OOI M2M via some common coding tools.
python (using the Requests library)
requests.get('https://ooinet.oceanobservatories.org/api/m2m/...', auth=(API_USERNAME, API_TOKEN))
urlread('https://ooinet.oceanobservatories.org/api/m2m/...', 'Authentication', 'Basic', 'Username', API_USERNAME, 'Password', API_TOKEN);
curl –k https://API_USERNAME:API_TOKEN@ooinet.oceanobservatories.org/api/m2m/...
http --auth API_USERNAME:API_TOKEN https://ooinet.oceanobservatories.org/api/m2m/...
- Data Team QC Database http://ooi.visualocean.net
- Data Portal https://ooinet.oceanobservatories.org
- Sampling Strategy https://ooi-website.whoi.edu/observation-and-sampling-approach
- Data Product Specifications https://ooi-website.whoi.edu/technical-data-package
- Data Product Algorithms https://github.com/oceanobservatories/ion-functions/tree/master/ion_functions/data
For additional help using the interface, if you encounter errors, or if you have suggestions, please contact the OOI Help Desk.
We will also be holding instructional webinars and posting additional guides and video tutorials in the Knowledge Base as they become available.