Access Data from the Ocean Color Instrument (OCI)

Access Data from the Ocean Color Instrument (OCI)#

Author(s): Anna Windle (NASA, SSAI), Ian Carroll (NASA, UMBC), Carina Poulin (NASA, SSAI)

Last updated: August 3, 2025

An Earthdata Login account is required to access data from the NASA Earthdata system, including NASA ocean color data.

Summary#

In this example we will use the earthaccess package to search for OCI products on NASA Earthdata. The earthaccess package, published on the Python Package Index and conda-forge, facilitates discovery and use of all NASA Earth Science data products by providing an abstraction layer for NASA’s Common Metadata Repository (CMR) API and by simplifying requests to NASA’s Earthdata Cloud. Searching for data is more approachable using earthaccess when compared to using low-level HTTP requests or working diectly with S3 object stores.

In short, earthaccess helps authenticate with Earthdata Login, makes search easier, and provides a stream-lined way to load data into xarray containers. For more on earthaccess, visit the documentation site. Be aware that earthaccess is under active development.

To understand the discussions below on downloading and opening data, we need to clearly understand where our notebook is running. There are three cases to distinguish:

The notebook is running on the local host. A Jupyter server on your laptop is a local host.
The notebook is running on a remote host, but it does not have direct access to the NASA Earthdata Cloud. For instance, GitHub Codespaces is a remote host that runs on a different cloud platform than the NASA Earthdata Cloud.
The notebook is running on a remote host that does have direct access to the NASA Earthdata Cloud.

Learning Objectives#

At the end of this notebook you will know:

How to store your NASA Earthdata Login credentials with earthaccess
How to use earthaccess to search for OCI data using search filters
How to download OCI data, but only when you need to

1. Setup#

We begin by importing the packages used in this notebook.

import earthaccess
import xarray as xr

2. NASA Earthdata Authentication#

Next, we authenticate using our Earthdata Login credentials. Authentication is not needed to search publicly available collections in Earthdata, but is always needed to access data. We use the login method from the earthaccess package. This will create an authenticated session when we provide a valid Earthdata Login username and password. The earthaccess package will search for credentials defined by environmental variables or within a .netrc file saved in the home directory. If credentials are not found, an interactive prompt will allow you to input credentials.

The persist=True argument ensures any discovered credentials are stored in a .netrc file, so the argument is not necessary (but it’s also harmless) for subsequent calls to earthaccess.login.

auth = earthaccess.login(persist=True)

3. Search for Data#

Collections on NASA Earthdata are discovered with the search_datasets function, which accepts an instrument filter as an easy way to get started. Each item in the list of collections returned in the search results has a “short-name”.

results = earthaccess.search_datasets(instrument="oci")

for item in results:
    summary = item.summary()
    print(summary["short-name"])

PACE_OCI_L0_SCI
PACE_OCI_L1A_SCI
PACE_OCI_L1B_SCI
PACE_OCI_L1C_SCI
PACE_OCI_L2_UVAI_UAA_NRT
PACE_OCI_L2_UVAI_UAA
PACE_OCI_L2_AER_UAA_NRT
PACE_OCI_L2_AER_UAA
PACE_OCI_L2_AOP_NRT
PACE_OCI_L2_AOP
PACE_OCI_L2_CLOUD_MASK_NRT
PACE_OCI_L2_CLOUD_MASK
PACE_OCI_L2_CLOUD_NRT
PACE_OCI_L2_CLOUD
PACE_OCI_L2_IOP_NRT
PACE_OCI_L2_IOP
PACE_OCI_L2_LANDVI_NRT
PACE_OCI_L2_LANDVI
PACE_OCI_L2_BGC
PACE_OCI_L2_BGC_NRT
PACE_OCI_L2_PAR_NRT
PACE_OCI_L2_PAR
PACE_OCI_L2_SFREFL_NRT
PACE_OCI_L2_SFREFL
PACE_OCI_L3B_AOT_NRT
PACE_OCI_L3B_AOT
PACE_OCI_L3B_AVW_NRT
PACE_OCI_L3B_AVW
PACE_OCI_L3B_CARBON
PACE_OCI_L3B_CARBON_NRT
PACE_OCI_L3B_CHL_NRT
PACE_OCI_L3B_CHL
PACE_OCI_L3B_KD_NRT
PACE_OCI_L3B_KD
PACE_OCI_L3B_FLH_NRT
PACE_OCI_L3B_FLH
PACE_OCI_L3B_IOP_NRT
PACE_OCI_L3B_IOP
PACE_OCI_L3B_LANDVI_NRT
PACE_OCI_L3B_LANDVI
PACE_OCI_L3B_PIC_NRT
PACE_OCI_L3B_PIC
PACE_OCI_L3B_POC_NRT
PACE_OCI_L3B_POC
PACE_OCI_L3B_PAR_NRT
PACE_OCI_L3B_PAR
PACE_OCI_L3B_RRS_NRT
PACE_OCI_L3B_RRS
PACE_OCI_L3B_SFREFL_NRT
PACE_OCI_L3B_SFREFL
PACE_OCI_L3M_UVAI_UAA_NRT
PACE_OCI_L3M_UVAI_UAA
PACE_OCI_L3M_AER_UAA_NRT
PACE_OCI_L3M_AER_UAA
PACE_OCI_L3M_AOT_NRT
PACE_OCI_L3M_AOT
PACE_OCI_L3M_AVW_NRT
PACE_OCI_L3M_AVW
PACE_OCI_L3M_CARBON
PACE_OCI_L3M_CARBON_NRT
PACE_OCI_L3M_CHL_NRT
PACE_OCI_L3M_CHL
PACE_OCI_L3M_CLOUD_MASK_NRT
PACE_OCI_L3M_CLOUD_MASK
PACE_OCI_L3M_CLOUD_NRT
PACE_OCI_L3M_CLOUD
PACE_OCI_L3M_KD_NRT
PACE_OCI_L3M_KD
PACE_OCI_L3M_FLH_NRT
PACE_OCI_L3M_FLH
PACE_OCI_L3M_IOP_NRT
PACE_OCI_L3M_IOP
PACE_OCI_L3M_LANDVI_NRT
PACE_OCI_L3M_LANDVI
PACE_OCI_L3M_PIC_NRT
PACE_OCI_L3M_PIC
PACE_OCI_L3M_POC_NRT
PACE_OCI_L3M_POC
PACE_OCI_L3M_PAR_NRT
PACE_OCI_L3M_PAR
PACE_OCI_L3M_RRS_NRT
PACE_OCI_L3M_RRS
PACE_OCI_L3M_SFREFL_NRT
PACE_OCI_L3M_SFREFL
PACE_OCI_L4M_MOANA
PACE_OCI_L4M_MOANA_NRT

The short name can also be found on Earthdata Search, directly under the collection name, after clicking on the “i” button for a collection in any search result.

Next, we use the search_data function (as opposed to search_datasets) to find granules within a collection. You can use search_data across collections too, but we’ll limit to a single collection by specifying one of the above short_name values. Let’s use the short_name for the PACE/OCI Level-2 biogeochemistry (BGC) products.

The count argument limits the number of granule records that are returned in the search results.

results = earthaccess.search_data(
    short_name="PACE_OCI_L2_BGC",
    count=1,
)

Displaying results shows the direct download link (try it!), along with a “quick-look” of some variable within the granule. The link will download the granule to your local machine, which may or may not be what you want to do. Even if you are running the notebook on a remote host, this download link will open a new browser tab or window and offer to save a file to your local machine. If you are running the notebook locally, this may be of use. More likely, you want to open or download the granules by following the steps below.

results[0]

Data: PACE_OCI.20240305T000858.L2.OC_BGC.V3_1.nc

Size: 14.45 MB

Cloud Hosted: True

We can refine our search by passing more parameters that describe the spatiotemporal domain of our use case. Here, we use the temporal parameter to request a date range and the bounding_box parameter to request granules that intersect with a bounding box. We can even provide a cloud_cover threshold to limit files that have a lower percetnage of cloud cover. We do not provide a count, so we’ll get all granules that satisfy the constraints.

tspan = ("2024-05-01", "2024-05-16")
bbox = (-76.75, 36.97, -75.74, 39.01)
clouds = (0, 50)

results = earthaccess.search_data(
    short_name="PACE_OCI_L2_BGC",
    temporal=tspan,
    bounding_box=bbox,
    cloud_cover=clouds,
)
len(results)