M2M (Machine to Machine)

Use OOI’s Machine to Machine Application Programming Interface (M2M API) to access full resolution datasets. M2M allows two software programs to communicate with each other. For OOI, 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 to download multiple data streams or data from multiple platforms, or set up recurring downloads to update an existing dataset. We have found it is helpful to familiarize 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.

M2M User Login Information

Before you can use the OOI M2M Interface/API, you need to establish 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.)

  1. Create a user account on ooinet.oceanobservatories.org, or use the CILogon button with an academic or Google account.
  2. Log in
  3. Navigate to the drop down menu screen in the top-right corner menu
  4. Click on the “User Profile” element of the drop down.
  5. Copy and save the following data from the user profile: API Username and API Token.

OOI-Maintained Software

The software packages maintained by OOI to facilitate M2M data requests are available in the oceanobservatories/ooi-data-explorations repository on GitHub which includes code for users of Matlab, R, Julia, and Python within directories named accordingly: You can access the OOI Data Explorations Github repository here.

While each of the python, Matlab, R, or Julia folders in this repository include some examples of OOI M2M data requests and usage of the OOI-maintained packages, additional examples for using the M2M API that were created by the community of OOI data users are also listed below.

OOI Machine to Machine (M2M) Examples

A number of Community Tools resources have been developed to assist users in getting started using M2M. The examples below are not exhaustive, but do include some step-by-step instructions and sample code that can be modified by users seeking access to data.

M2M Quickstart Examples

The following examples show how the OOI API interface can be used to request, download, and plot OOI data using various programming libraries.

API Endpoint Quickstart Matlab Quickstart Python Quickstart R Quickstart

M2M Demo Workbooks

The following Python notebooks demonstrate how the Python requests library can be used to access data from the OOI M2M web service.

Basic M2M Examples JSON Requests NetCDF Requests Real-Time Requests

OOIFB Northeast Pacific Community Workshop Presentations

This workshop was hosted by the OOI Facility Board with funding provided by the National Science Foundation in 2022. An overview of OOI data products, user interfaces, and system features was provided along with demonstrations using M2M and other data access tools. Full details about this workshop are available here.

Using M2M: Programmatic Interaction with OOI Data & Metadata Northeast Pacific OOI Community Workshop M2M Tutorial

Other Examples

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 Synchronous Requests and Basic Plotting Example 1 – Requesting OOI Data in NetCDF Format

Demonstrates how the OOI M2M interface can be used to retrieve information about OOI instruments in the database and to request downloads for instrument data.

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 filesDemonstrates 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.

Tools to access OOI M2M Web Services

Here is a quick rundown on how to access the OOI M2M using some common coding tools.

Python (using the library)

1 | requests.get('https://ooinet.oceanobservatories.org/api/m2m/...', auth=(API_USERNAME, API_TOKEN))

Matlab

1 | urlread('https://ooinet.oceanobservatories.org/api/m2m/...', 'Authentication', 'Basic', 'Username', API_USERNAME, 'Password', API_TOKEN);

Curl

1 | curl –k https://API_USERNAME:API_TOKEN@ooinet.oceanobservatories.org/api/m2m/…

HTTPS

1 | http --auth API_USERNAME:API_TOKEN https://ooinet.oceanobservatories.org/api/m2m/...

Additional Resources

Data Team QC Data Portal Sampling Strategy Data Product Specifications Data Product Algorithms

 

For additional help using the interface, or if you encounter errors, or if you have suggestions on how to improve this interface, please either contact the Helpdesk or engage with colleagues on Discourse