# ESS-DIVE Dataset API

## Quickstart

First time using APIs? Click on an action below to see complete tutorials that walkthrough each Dataset API operation! No coding experience is required to try out a tutorial.

<table data-view="cards" data-full-width="false"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Search for Datasets</td><td><a href="/pages/TrWUosQoGZwRIyYy1c5t">/pages/TrWUosQoGZwRIyYy1c5t</a></td></tr><tr><td>Submit Datasets</td><td><a href="/pages/mHbnTiV45qMxHlbjVIFg">/pages/mHbnTiV45qMxHlbjVIFg</a></td></tr><tr><td>Project Dataset Metrics</td><td><a href="https://github.com/ess-dive/essdive-tutorials/blob/main/manage_data/Project%20Dataset%20Metric%20Report%20-%20Python.ipynb">https://github.com/ess-dive/essdive-tutorials/blob/main/manage_data/Project%20Dataset%20Metric%20Report%20-%20Python.ipynb</a></td></tr><tr><td>Share Datasets</td><td><a href="https://github.com/ess-dive/essdive-tutorials/blob/main/manage_data/ShareDatasets_Python.ipynb">https://github.com/ess-dive/essdive-tutorials/blob/main/manage_data/ShareDatasets_Python.ipynb</a></td></tr></tbody></table>

## Getting started with ESS-DIVE Dataset API                                  (Package Service API version 1)

ESS-DIVE's Dataset API is a REST API with a variety of operations available that allow you to programmatically manage datasets using HTTP requests. This is an alternative to using the [ESS-DIVE Online](https://data.ess-dive.lbl.gov/) form for managing data.&#x20;

This service encodes metadata using the [JSON-LD](https://json-ld.org/) specification. JSON-LD is a schema to encode linked Data using JSON, and is [used by Google](https://developers.google.com/search/docs/data-types/dataset) to index metadata for searches. The use of the standardized JSON-LD schema dramatically increases the visibility of datasets, and also enable projects to create one-time code that can be reused for periodic uploads of datasets to ESS-DIVE.

ESS-DIVE has a variety of resources available to help you get started with the Dataset API. We have example code and usage documentation available for new and experienced coders. **In addition to the linked resources below, you'll also find user-friendly introductions to specific API operations within this documentation!** Find these under the relevant Submit, Manage, and Search sections. &#x20;

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Dataset API Tutorials</strong></td><td>Browse through all ESS-DIVE's Jupyter Notebook Tutorials.</td><td><a href="https://github.com/ess-dive/essdive-tutorials">https://github.com/ess-dive/essdive-tutorials</a></td></tr><tr><td><strong>Technical Example Scripts</strong></td><td>Interested in building scripts to automate your publication workflow? Our GitHub repo has all example code available in R, Python and Java.</td><td><a href="https://github.com/ess-dive/essdive-package-service-examples">https://github.com/ess-dive/essdive-package-service-examples</a></td></tr><tr><td><strong>Technical API Documentation</strong></td><td>Experienced coders can come here to see all available HTTP operations and find details on expected schema for building custom scripts.</td><td><a href="https://api.ess-dive.lbl.gov/#/">https://api.ess-dive.lbl.gov/#/</a></td></tr></tbody></table>

Provide feedback on this service to <ess-dive-support@lbl.gov>.

## Get Authentication Token

1. Visit ESS-DIVE
   1. **Search & Download:** [https://data.ess-dive.lbl.gov](https://api.ess-dive.lbl.gov/#/)
   2. **Submit & Manage Datasets:** [https://data-sandbox.ess-dive.lbl.gov](https://data-sandbox.ess-dive.lbl.gov/data)
2. Sign in with Orcid
3. Click your Name in the right hand corner and select *My Profile* (Figure 1)
4. Now Click the *Settings>Authentication Token* (Figure 2)
5. Scroll down and click *Copy* on the “Token” tab to get your authentication token (Figure 2)

![Figure 1. Hover over your name and click on My Profile ](/files/-Mj1ayVTCZCUrzWOa3jB)

![Figure 2. Click on Authentication Token under Settings and copy the token](/files/-LkaMEbV9vrGoK_Qkjdc)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ess-dive.lbl.gov/programmatic-tools/ess-dive-dataset-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.