Ctrlk
Contact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Search with Dataset API

Public datasets can be programmatically searched and downloaded by anyone using the Dataset API. ORCID login is required to use the API.

Dataset API Resources: Setup | Technical Documentation | Search Tutorials | Search Code Examples

About Searches with the Dataset API

The Dataset API is a great tool for searching through multiple datasets at the same time. Unlike the website (https://data.ess-dive.lbl.gov/), you can search for exact keyword matches and download multiple datasets at once.

Query Parameters:

  • providerName: The ESS project that published the dataset. Exact project names are required, find yours using ESS-DIVE's Project List

  • keywords: Search for datasets that have an exact match for all the given keywords

  • creator: The creator/submitter of datasets

  • text: Searches any metadata field that contains the passed text

  • datePublished: Dataset publication date

  • beginDate & endDate: Temporal range of the data

  • bbox: Coordinate bounding boxes of the data

  • lat, long, radius: Specified coordinate range for the data

  • sort: Order in which the datasets are returned

To see examples of what a request query using these parameters looks like, go to our Code Examples page:

Code Examples

Dataset API Search Quick Start

Get started with ESS-DIVE's Dataset API right away with our Jupyter Notebook tutorials! No coding knowledge is necessary to run the notebooks. Follow these quick steps to check it out on our GitHub.

1. Visit ESS-DIVE's API Tutorial GitHub

Dataset API search tutorials are currently only offered in Python.

LogoGitHub - ess-dive/essdive-tutorials: Tutorials for ESS-DIVEGitHub
Click this link to go to the GitHub.

2. Launch the notebooks with the click of a button

You can select the Google Colab or Jupyter+R Binder button to launch the tutorials. We recommend Google Colab for a smoother experience (a Google account is required to use Colab).

At the top of the Github README, select preferred tool.
Google Colab Option: Select one of the tutorials.
Jupyter Binder Option: Select a folder and then a tutorial.

You'll need to login to ESS-DIVE with your ORCID to search with the Dataset API. See steps 1 and 2 in our registration instructions for help logging in.

3. Open the search_data folder

We recommend starting with the tutorial titled ESS PI Meeting 2025: Using Data - Python.ipynb. Follow the instructions to enter your login information. Click the play icon to run the cells and see the Dataset API in action.

Preview of the Google Colab interface

What can you do with the Dataset API Search Capabilities?

Once you have multiple metadata and data files in hand, you can perform custom searches and visualizations directly in the notebook. Here's an idea of some of the things you can do that are demonstrated in ESS-DIVE's data search tutorials:

  • Review and download relevant datasets and their files,

  • Preview file sizes,

  • Create publication reports,

  • Look up the view, download, and citation metrics for each dataset,

  • Get data citations,

  • Visualize data directly after finding datasets, and

  • Leverage the DeepDive API along with the Dataset API for even more powerful file-level search!

What's Next?

After you've identified some datasets you're interested in, try out the Deep Dive API to query and explore certain* file contents!

*Available for datasets following the File Level Metadata (FLMD) and CSV Guidelines Reporting Formats

Search with Deep Dive API

Last updated