# 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="../searching-and-accessing-data/search-with-dataset-api">search-with-dataset-api</a></td></tr><tr><td>Submit Datasets</td><td><a href="../contributing-data/submit-data-with-the-dataset-api">submit-data-with-the-dataset-api</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 ](https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgU7GrufgIOpY1Ufd5R%2F-Mj1_ufatnr_-vuR-edq%2F-Mj1ayVTCZCUrzWOa3jB%2Fmy-profile.png?alt=media\&token=30acc227-7530-425a-88f5-e80637d1f89c)

![Figure 2. Click on Authentication Token under Settings and copy the token](https://3166205607-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LgU7GrufgIOpY1Ufd5R%2F-LkaM78iKT0zasc8fJdJ%2F-LkaMEbV9vrGoK_Qkjdc%2Fimage.png?alt=media\&token=7df47405-0ca2-4c7d-9e3b-a33cf681c7d8)