Setup and Troubleshoot

All Dataset API code examples require installation of certain packages and authentication from your ESS-DIVE account. This page provides instructions for setting up the Dataset API for your preferred coding language.

For additional information about the API, review the technical documentation at https://api-sandbox.ess-dive.lbl.gov.

ESS-DIVE Test API URL (Sandbox): https://api-sandbox.ess-dive.lbl.gov ESS-DIVE Production API URL: https://api.ess-dive.lbl.gov/ Help Desk: [e-mail]

Setup Code

Step 1: Get Authentication Token: Copy your authentication token from ESS-DIVE, then paste it into the code where specified in the example.

Step 2: Setup your code in your preferred coding language as follows.

Python

Setup in Python

Install the following python module into your python environment

$ pip install requests

In a python console or script add the following lines to setup your script.

import requests
import os
import json

token = "<Enter your authorization token here>"
base = "https://api-sandbox.ess-dive.lbl.gov/"
header_authorization =  "bearer {}".format(token)
endpoint = "packages"

Check that your token is up-to-date; it expires after 24 hours

R

Setup in R

Install the following R packages

install.packages("httr")
install.packages("jsonlite")
install.packages("readr")

#Require the package so you can use it
require("jsonlite")
require("httr")
library(readr)

Setup the Dataset API information

token <- "<Enter your authentication token here>"
base <- "https://api-sandbox.ess-dive.lbl.gov"
header_authorization <- paste("bearer",token, sep=" ")
endpoint <- "packages"

Check that your token is up-to-date; it expires after a 24 hours

Java

Setup in Java

To be able to do the setup correctly, you need a few prerequisites installed on your machine which are unzip, java, javac and curl.

Inside your project directory create a java file named essdive.java and a directory lib. The following are the Linux commands to create the file and directory:

touch essdive.java
mkdir lib
cd lib

Add http client, http core and commons logging from Apache HTTPComponents libraries version 4.5.6 and json_simple-1.1 into your lib directory by downloading its zip file, extracting it and moving it inside lib.

curl -O http://ftp.wayne.edu/apache//httpcomponents/httpclient/binary/httpcomponents-client-4.5.6-bin.zip

curl -O https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/json-simple/json_simple-1.1.jar

curl -O http://mirror.cc.columbia.edu/pub/software/apache//commons/io/binaries/commons-io-2.6-bin.tar.gz

tar -xvzf commons-io-2.6-bin.tar.gz
mv commons-io-2.6/commons-io-2.6.jar .


unzip httpcomponents-client-4.5.6-bin.zip 
mv httpcomponents-client-4.5.6/lib/* . 

Open essdive.java document created earlier using any text editor and add the following code to start importing the libraries needed for your java code:

import java.io.File;
import java.io.IOException;

//JSON imports
import org.apache.http.HttpEntity;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;

//Apache http imports
import org.apache.commons.io.FileUtils;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.HttpResponse;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.entity.StringEntity;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.mime.FormBodyPart;
import org.apache.http.entity.mime.FormBodyPartBuilder;
import org.apache.http.entity.mime.HttpMultipartMode;
import org.apache.http.util.EntityUtils;
import org.apache.http.entity.mime.MultipartEntityBuilder;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.client.methods.HttpGet;

Definition of configuration variables

Inside the main function you should define your configuration variables:

Note: You will have to close the class and main blocks by adding two closing curly braces at the end of the document.

public class essdive {

public static void main(String[] args) {
 //Configuration variables
  String token = "<Enter your authorization token here>";
  String base = "https://api-sandbox.ess-dive.lbl.gov/";
  String header_authorization = "bearer " + token;
  String endpoint = "packages";

Then define your utilities objects:

         //Utilities objects 
        CloseableHttpClient httpClient = HttpClientBuilder.create().build();

Check that your token is up-to-date; it expires after a 24 hours

Troubleshoot

Python

Python Troubleshooting Tips

{"detail":"You do not have authorized access"}

This error message indicates your token is either incorrect or expired. Please follow the instructions on the ESS-DIVE Dataset API page to retrieve a new token.

{"detail":"One or more fields raised validation errors.","errors":["provider/member 'familyName' is a required property"]}

This error message indicates a required field is missing from your JSON. In this case it is the "familyName". Revise your JSON to include the mandatory fields.

FileNotFoundError                         Traceback (most recent call last)
<ipython-input-28-7ae5b841a5b0> in <module>
      5 
      6 files_tuples_array.append((("json-ld", json.dumps(json_ld))))
----> 7 files_tuples_array.append(("data", open(file_directory ,'rb')))
      8 
      9 post_packages_url = "{}{}".format(base,endpoint)

FileNotFoundError: [Errno 2] No such file or directory: 'trials.csv'

This error message indicates the file entered was not found. This could be because you are searching in the wrong directory or because you misrepresented the file name.

R

R Troubleshooting Tips

 results = content(post_package)
>  attributes(results)$names
[1] "detail"
>  results$detail
[1] "You do not have authorized access"
>  results$errors
NULL
>  results$viewUrl
NULL

This error message indicates your token is either incorrect or expired. Please follow the instructions on the ESS-DIVE Dataset API page to retrieve a new token.

Error: 'C:\Users\Person\Desktop\API\API_Tutorials.json' does not exist.

This error message indicates the file entered was not found. This could be because you are searching in the wrong directory or because you misrepresented the file name.

Java

Currently no troubleshooting tips are available in Java.