# Search with Dataset API

**Dataset API Resources**: [Setup](https://docs.ess-dive.lbl.gov/programmatic-tools/ess-dive-dataset-api#get-authentication-token) | [Technical Documentation](https://api.ess-dive.lbl.gov/#/) | [Search Tutorials](https://github.com/ess-dive/essdive-tutorials/tree/main/search_data) | [Search Code Examples](https://docs.ess-dive.lbl.gov/searching-and-accessing-data/search-with-dataset-api/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](https://data.ess-dive.lbl.gov/projects),
* **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, and
* **datePublished**: Dataset publication date

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

{% content-ref url="search-with-dataset-api/code-examples" %}
[code-examples](https://docs.ess-dive.lbl.gov/searching-and-accessing-data/search-with-dataset-api/code-examples)
{% endcontent-ref %}

## Dataset API Search Quick Start&#x20;

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

{% embed url="<https://github.com/ess-dive/essdive-tutorials/tree/main>" %}
Click this link to go to the GitHub.
{% endembed %}

#### 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*).

<div data-full-width="true"><figure><img src="https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgU7GrufgIOpY1Ufd5R%2Fuploads%2FPdw0dyddPYRW5loumjke%2FScreenshot%202025-04-10%20at%205.54.15%E2%80%AFAM.png?alt=media&#x26;token=bc01fe25-a98d-466b-8361-5340194523f4" alt="" width="375"><figcaption><p>At the top of the Github README, select preferred tool.</p></figcaption></figure> <figure><img src="https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgU7GrufgIOpY1Ufd5R%2Fuploads%2FB2gSK73QcSlIRVW3fORC%2FColab-startup.png?alt=media&#x26;token=b35b7cef-4dca-497c-9e02-4efd8781b563" alt="" width="375"><figcaption><p><strong>Google Colab Option:</strong> Select one of the tutorials.</p></figcaption></figure> <figure><img src="https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgU7GrufgIOpY1Ufd5R%2Fuploads%2FU01uT7x5oMqvTlS3OSEr%2FScreenshot%202025-04-10%20at%205.57.20%E2%80%AFAM.png?alt=media&#x26;token=f6165aff-48d3-427f-97b3-6aaf8ad75338" alt="" width="375"><figcaption><p><strong>Jupyter Binder Option:</strong> Select a folder and then a tutorial.</p></figcaption></figure></div>

{% hint style="info" %}
You'll need to **login** to [ESS-DIVE](https://data.ess-dive.lbl.gov/data) with your ORCID to search with the Dataset API. See steps 1 and 2 in our [registration instructions](https://docs.ess-dive.lbl.gov/contributing-data/new-contributor-registration#id-1.-create-an-orcid) for help logging in.
{% endhint %}

#### 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.&#x20;

<figure><img src="https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgU7GrufgIOpY1Ufd5R%2Fuploads%2FZSoBgf8ndJY6I2soBuOW%2FColab-searchDataNB.png?alt=media&#x26;token=354b1fef-1140-4a34-9194-2d2c081bf563" alt=""><figcaption><p>Preview of the Google Colab interface</p></figcaption></figure>

***

## **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,&#x20;
* 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**](https://docs.ess-dive.lbl.gov/searching-and-accessing-data/search-with-deep-dive-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!&#x20;

*\*Available for datasets following the* [*File Level Metadata (FLMD)*](https://ess-dive.gitbook.io/file-level-metadata-reporting-format) *and* [*CSV Guidelines*](https://ess-dive.gitbook.io/csv-file-structure-reporting-format) *Reporting Formats*

{% content-ref url="search-with-deep-dive-api" %}
[search-with-deep-dive-api](https://docs.ess-dive.lbl.gov/searching-and-accessing-data/search-with-deep-dive-api)
{% endcontent-ref %}