GOLD API

GOLD API

To access GOLD API either in browser or programmatically, you need an ORCID account if you are not a LBL staff, or a LBL account if you are.
You will also need to set up multi-factor authentication (MFA) using an authenticator App such as Google Authenticator.
This API login system is different from the current JGI SSO login required for using the GOLD website. In future we will be merging these two login systems and those details will be forthcoming.

To access GOLD API in the browser, make sure you have signed in using the “Log In” link above.
To access API documentation, click “API Documentation” link on the navigation bar above.
To access GOLD API programmatically, you need to obtain an offline token using the “Request Token ” button below.

The offline token allows your program to skip the login process including MFA.
The offline token will expire if you stop using it for 365 days.

How to use the offline token in your program:

In your program, store the token you received in a variable called OFFLINE_TOKEN.
Your program executes the following command to exchange the offline token for a temporary access token which will be valid for 12 hours.

             curl https://gold-ws.jgi.doe.gov/exchange?offlineToken=$OFFLINE_TOKEN

Above command will return an access token. Your program stores the access token in a variable called ACCESS_TOKEN.
Your program executes the following command to call API to retrieve data. Note that the part of the URL here, “/organisms?projectGoldId=Gp0451293”, is just an example and should be replaced based on the data you want to retrieve.

             curl https://gold-ws.jgi.doe.gov/api/v1/organisms?projectGoldId=Gp0451293 -H "Accept: application/json" -H  "Authorization: Bearer $ACCESS_TOKEN"

Your program can be written to execute Step 2 to renew the ACCESS_TOKEN at the end of 12 hours if your program is still running.
Once your program is set up according to the above steps, it does not need to be changed unless your offline token expires (after being inactive for 365 days). In that case, simply come to this page to obtain another offline token and replace the one in your program.

Here is an example script callapi.sh that is written in bash to demonstrate the above steps. Feel free to use any programming language of your choice.

             #!/bin/bash

# This is a sample script that uses offline token to exchange for access token then call API to receive data

#1. Paste the offline token you received
OFFLINE_TOKEN=[ENTER OFFLINE TOKEN HERE AND REMOVE THE BRACKETS]

#2. Exchange the offline token for an access token
ACCESS_TOKEN=$(curl https://gold-ws.jgi.doe.gov/exchange?offlineToken=$OFFLINE_TOKEN)

#3. Fire calls to API using the access token
DATA=$(curl https://gold-ws.jgi.doe.gov/api/v1/organisms?projectGoldId=Gp0451293 -H "Accept: application/json" -H "Authorization: Bearer $ACCESS_TOKEN")

echo $DATA

To run this script:

Paste the offline token you received into the script
On command line, run chmod 755 callapi.sh to make it executable
Run the script from command line: ./callapi.sh The data returned from API will be printed out on the console like the following (example only):

[{"organismGoldId":"Go0526350","organismName":"Paraburkholderia sp. JPY156","ncbiTaxId":1926495,"ncbiSuperkingdom":"Bacteria","ncbiKingdom":null,"ncbiPhylum":"Proteobacteria","ncbiClass":"Betaproteobacteria","ncbiOrder":"Burkholderiales","ncbiFamily":"Burkholderiaceae","ncbiGenus":"Paraburkholderia","ncbiSpecies":"Paraburkholderia sp.","bioticRelationships":"","oxygenRequirement":null,"metabolism":"","energySources":"","gramStain":null,"isolationPubmedId":null,"habitat":"","sampleCollectionSite":null,"ecosystemPathId":1,"ecosystem":null,"ecosystemCategory":null,"ecosystemType":null,"ecosystemSubtype":null,"specificEcosystem":null,"isolationHostName":null,"hostTaxonomyId":null,"hostBodySite":null,"hostBodySubsite":null,"salinity":null,"salinityConcentration":null,"cellDiameter":null,"cellShape":null,"color":null,"motility":null,"ph":"null","pressure":null,"sporulation":null,"carbonSource":null,"growthTemperature":"null","cellLength":null,"cultured":"Yes","modDate":"2019-09-11","addDate":"2019-08-24"}]