DOE Data Explorer

API Documentation

Introduction

Please note: This version of the Data Explorer API (v0.1) is a release candidate being made available for review and testing, and will be deprecated in the near future in favor of an official v1 release. Please contact us with any suggestions or questions.

The DOE Data Explorer API allows you query the Department of Energy's Data Explorer repository of datasets and collections resulting from DOE research funding.

The API is built on a REST architecture, providing predictable URLs that make writing applications easy. The API is HTTP-based, so it can be accessed using a wide variety of clients; most examples are illustrated using the cURL command to demonstrate basic use cases.

The list of resources available through the API, and their corresponding reference documenation, will always be made available at the API root endpoint (this document).

API Root Endpoint

http://www.osti.gov/dataexplorer/api/v0.1

General Guidelines

Each resource endpoint in the API will vary slightly in some respects, such as what query parameters are valid for that type of request and how the expected output may be structured. These variations will be outlined in detail in the resource-specific sections below. There are, however, some general rules and expectations that are common to all interactions with the API.

HTTP Methods

The Data Explorer API uses the HTTP verb (method) associated with the incoming request to identify the type of action being performed. Note that at this time the Data Explorer API has methods for querying data only, and therefore all requests to the API will be GET requests.

Request Methods
Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing resource actions.
Not currently valid for Data Explorer API resource requests
PUT Used for updating resources.
Not currently valid for Data Explorer API resource requests
DELETE Used for deleting resources.
Not currently valid for Data Explorer API resource requests

Using the GET method, you can retrieve a list (collection) of resources or details of a particular resource.

To get a list of datasets / collections:

$ curl http://www.osti.gov/dataexplorer/api/v0.1/records

To get details of a dataset with a particular ID:

$ curl http://www.osti.gov/dataexplorer/api/v0.1/records/111111

Response Formats

By default, results from the Data Explorer API will be returned in JSON format. By specifying an expected mime type in the Accept header of the request, results can also be returned in any of JSON, XML, or Bibtex formats.

Format Types and Accept Headers
Format Accept header
JSON application/json
XML application/xml
Bibtex application/x-bibtex

Specifying the Accept header in the request, you can retrieve results in a particular format.

To get a dataset's metadata in JSON format:

$ curl http://www.osti.gov/dataexplorer/api/v0.1/records/111111 \
	-H 'Accept: application/json'

To get a dataset's metadata in XML format:

$ curl http://www.osti.gov/dataexplorer/api/v0.1/records/111111 \
	-H 'Accept: application/xml'

To get a dataset's metadata in Bibtex format:

$ curl http://www.osti.gov/dataexplorer/api/v0.1/records/111111 \
	-H 'Accept: application/x-bibtex'

Response Headers

Responses from the API will include certain common HTTP headers, providing details about the response or the included content.

Common Response Headers
Response Header Description
Date The date the repsonse is issued, in RFC 1123 format
Content-Type The mime type in which the response data is formatted
X-Total-Count For reponses containing data, the number of records returned in the current response
Link If more matching records are available than are returned in the current response, this will contain links to more pages in RFC 5988 format

Example Response Headers

HTTP/1.1 200 OK

Date: Thu, 26 May 2016 16:25:04 GMT
Content-Type: application/json
X-Total-Count: 50
Link: <http://www.osti.gov/dataexplorer/api/v0.1/records?page=2>; rel="next", <http://www.osti.gov/dataexplorer/api/v0.1/records?page=3>; rel="last"
Content-Length: 3911

Pagination

Requests that return multiple records will be paginated to 20 records by default; the number of records per page can be modified by specifying a numerical value for the ?rows parameter, and the specific page with the ?page parameter (default 1). If more matching records exist, the Link response header will contain links to additional pages of data, in RFC 5988 format. The specific type of link is denoted by the "rel" value.

Link Header Rel Values
Name Description
next The link relation for the immediate next page of results
last The link relation for the last page of results
first The link relation for the last page of results
prev The link relation for the immediate previous page of results

Example Link Header Values


$ curl http://www.osti.gov/dataexplorer/api/v0.1/records?page=2&rows=20

HTTP/1.1 200 OK

...
X-Total-Count: 250
Link:
<http://www.osti.gov/dataexplorer/api/v0.1/records?page=3&rows=20>; rel="next",
<http://www.osti.gov/dataexplorer/api/v0.1/records?page=13&rows=20>; rel="last",
<http://www.osti.gov/dataexplorer/api/v0.1/records?page=1&rows=20>; rel="first",
<http://www.osti.gov/dataexplorer/api/v0.1/records?page=1&rows=20>; rel="prev"
...

Record Model

Responses returning data all return the same basic structure, formatted as appropriate for the content type requested.

HTTP Status Codes

A successful response from the API will always return an HTTP status code of 200.

HTTP Success Status
Status Description
200 OK

Record Fields

Results are always presented as a list of Record objects, formatted according to the content type requested. For JSON, records are returned as an array of objects. For XML, records are returned as <record> elements wrapped in a <records> container. BibTex results are formatted serially.

Record Fields
Field Name Description
osti_idThe unique OSTI identifier for the record
titleA name or title by which the record is known
authorsThe person(s) primarily responsible for the creation of the data
subjectsA list of subjects, keywords, or key phrases describing the resource
descriptionA short description or abstract
publisherThe name of the entity that holds, archives, distributes, releases, or produces the resource
country_publicationThe country in which this version of the record was published
publication_dateThe publication date, in ISO-8601 format
entry_dateThe date the record was added or last modified, in ISO-8601 format
doiThe Digital Object Identifier (DOI)
product_typeThe product type of the record (one of "Dataset" or "Collection")
dataset_content_typeA descriptor that best describes the resource content (simulation, numeric, etc)
languageThe primary language of the resource
availabilityIf applicable, the office or organization to refer access requests to
research_orgIf credited, the organization name primarily responsible for conducting the research
sponsor_orgIf credited, the organzation name that sponsored / funded the research
contributor_orgIf credited, the organzation(s) contributing to the dataset
formatAdditional format / paging information
report_numberThe report number associated with the entry
doe_contract_numberThe DOE contract number associated with the entry

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "title": "Mastering the Data Explorer API",
        "dataset_content_type": [
            "Numeric Data",
            "Multimedia"
        ],
        "osti_id": "1314892",
        "subjects": [
            "technology",
            "natural language computing",
        ],
        "format": "Medium: X",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
        "doe_contract_number": "AC02-76SF00515; 11327902",
        "sponsor_org": "USDOE",
        "research_org": "None",
        "contributing_org": "Contributing Org Name",
        "language": "English",
        "availability": "",
        "entry_date": "2015-10-02T04:00:00Z",
        "product_type": "Dataset",
        "report_number": "None",
        "country_publication": "United States",
        "publication_date": "2014-09-01T04:00:00Z",
        "publisher": "Science Org Name",
        "doi": "10.1103/ScienceOrgName.113.134802",
        "authors": [
            "Hemsing, E.",
            "Marinelli, A.",
            "Marcus, G.",
            "Xiang, D."
        ]
    }
]
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0"?>
<records>
    <record>
        <title>Mastering the Data Explorer API</title>
        <dataset_content_types>
            <dataset_content_type>Numeric Data</dataset_content_types>
            <dataset_content_type>Multimedia</dataset_content_types>
        </dataset_content_types>
        <osti_id>1314892</osti_id>
        <subjects>
            <subject/>
        </subjects>
        <format>Medium: X</format>
        <description>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</description>
        <doe_contract_number>AC02-76SF00515; 11327902</doe_contract_number>
        <sponsor_org>USDOE</sponsor_org>
        <research_org>None</research_org>
        <contributing_org>Contributing Org Name</contributing_org>
        <language>English</language>
        <availability/>
        <entry_date>2015-10-02T04:00:00Z</entry_date>
        <product_type>Dataset</product_type>
        <report_number>None</report_number>
        <country_publication>United States</country_publication>
        <publication_date>2014-09-01T04:00:00Z</publication_date>
        <publisher>Science Org Name</publisher>
        <doi>10.1103/ScienceOrgName.113.134802</doi>
        <authors>
            <author>Hemsing, E.</author>
            <author>Marinelli, A.</author>
            <author>Marcus, G.</author>
            <author>Xiang, D.</author>
        </authors>
    </record>
</records>
HTTP/1.1 200 OK
Content-Type: application/x-bibtex
@misc{dataset-id,
  title        = {Mastering the Data Explorer API},
  author       = {Hemsing, E. and Marinelli, A. and Marcus, G. and Xiang, D.},
  abstractNote = {Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.},
  doi          = {10.1103/ScienceOrgName.113.134802},
  place        = {United States},
  year         = 2014,
  month        = 9,
  note         = {An optional note}, 
}

Error Model

If for some reason the API returns an error response, it will be formatted as appropriate for the content type requested. All error responses have the same basic structure.

HTTP Status Codes

Errors will be returned with an HTTP error status code appropriate to the type of error encountered.

HTTP Error Status
Status Description
400 Bad request
401 Unauthorized
404 Resource Not Found
405 Method Not Allowed
500 Internal Error

Error Fields

Errors are always presented as a single object, formatted according to the content type requested.

Error Fields
Field Name Description
statusCodeThe response error code, duplicated for convenience
statusMessageA brief description of the error type
errorDescriptionA more detailed description of the specific error cause

Example Error

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "statusCode": 404,
    "statusMessage": "Not Found",
    "errorDescription": "No record matching the supplied OSTI ID was found"
}
HTTP/1.1 404 Not Found
Content-Type: application/xml
<?xml version="1.0"?>
<error>
    <statusCode>404</statusCode>
    <statusMessage>Not Found</statusMessage>
    <errorDescription>No record matching the supplied OSTI ID was found</errorDescription>
</error>
HTTP/1.1 404 Not Found
Content-Type: application/x-bibtex
404
Not Found
No record matching the supplied OSTI ID was found

Endpoints

The Data Explorer API currently supports two endpoints, both of which are data retrieval endpoints and as such only GET method requests are valid. All endpoints are relative to the root endpoint.

API Root Endpoint

http://www.osti.gov/dataexplorer/api/v0.1

Record List (Search)

GET /records

The record list endpoint allows you to search for lists of records in Data Explorer by a variety of criteria.

Record List Query Parameters
Parameter Description
qGeneral query field, will search full record for provided terms
osti_idThe unique OSTI identifier for a record
fulltextSearches the article full text (if available) for the provided terms
biblioSearches the bibliographic information for the provided terms
authorSearches the author entries
titleSearches within document titles
identifierFinds records based on common identifiers (report number, contract number, etc.)
sponsor_orgSearches the sponsoring organization field
research_orgSearches the research organization field
contributing_orgSearches the contributing organization field
source_idA code specifying the organization that submitted the record
dataset_content_typeSpecifies the category of dataset / collection
publication_date_startBeginning publication date boundary in MM-DD-YYYY format
publication_date_endEnd publication date boundary in MM-DD-YYYY format
entry_date_startBeginning entry date boundary in MM-DD-YYYY format
entry_date_endEnding entry date boundary in MM-DD-YYYY format
languageFinds records by language
countryFinds records by country of publication
sortSpecifies a field name on which to sort
orderSpecifies the sort order (one of asc or desc)
rowsThe number of rows per page to return (default 20)
pageThe specific page of records to return (default 1)

Record List Endpoint

http://www.osti.gov/dataexplorer/api/v0.1/records

Single Record by ID

GET /records/{osti_id}

The single record by id endpoint allows you to retrieve details for a specific record by providing the appropriate OSTI ID value as the key in the request path.

Record List Query Parameters
Parameter Description
none

Single Record Endpoint

http://www.osti.gov/dataexplorer/api/v0.1/records/{osti_id}

The DOE Data Explorer API is actively in development; the documentation should be kept up to date with the functionality of the current release. If you have any questions or suggestions, please let us know.