The ETDEWEB API allows you to query the ETDEWEB World Energy Base where you can search and explore literature references and many full text documents.
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 documentation, will always be made available at the API root endpoint (this document).
https://www.osti.gov/etdeweb/api/v1Each 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.
The ETDEWEB 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 ETDEWEB 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 ETDEWEB API resource requests |
| PUT | Used for updating resources. Not currently valid for ETDEWEB API resource requests |
| DELETE | Used for deleting resources. Not currently valid for ETDEWEB 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 records:
$ curl https://www.osti.gov/etdeweb/api/v1/recordsTo get details of a dataset with a particular ID:
$ curl https://www.osti.gov/etdeweb/api/v1/records/{osti id}
By default, results from the ETDEWEB 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 https://www.osti.gov/etdeweb/api/v1/records/{osti id} \
-H 'Accept: application/json'To get a dataset's metadata in XML format:
$ curl https://www.osti.gov/etdeweb/api/v1/records/{osti id} \
-H 'Accept: application/xml'To get a dataset's metadata in Bibtex format:
$ curl https://www.osti.gov/etdeweb/api/v1/records/{osti id} \
-H 'Accept: application/x-bibtex'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 response is issued, in RFC 1123 format |
| Content-Type | The mime type in which the response data is formatted |
| X-Total-Count | For responses 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 ETDEWEB in RFC 5988 format |
HTTP/1.1 200 OK
Date: Thu, 26 May 2016 16:25:04 GMT
Content-Type: application/json
X-Total-Count: 50
Link: <https://www.osti.gov/etdeweb/api/v1/records?page=2>; rel="next", <https://www.osti.gov/etdeweb/api/v1/records?page=3>; rel="last"
Content-Length: 3911Requests 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 ETDEWEB 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 |
$ curl https://www.osti.gov/etdeweb/api/v1/records?page=2&rows=20
HTTP/1.1 200 OK
...
X-Total-Count: 250
Link:
<https://www.osti.gov/etdeweb/api/v1/records?page=3&rows=20>; rel="next",
<https://www.osti.gov/etdeweb/api/v1/records?page=13&rows=20>; rel="last",
<https://www.osti.gov/etdeweb/api/v1/records?page=1&rows=20>; rel="first",
<https://www.osti.gov/etdeweb/api/v1/records?page=1&rows=20>; rel="prev"
...Responses returning data all return the same basic structure, formatted as appropriate for the content type requested.
A successful response from the API will always return an HTTP status code of 200.
| HTTP Success Status | |
|---|---|
| Status | Description |
| 200 | OK |
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_id | The unique OSTI identifier for the record |
| title | A name or title by which the record is known |
| description | A short description or abstract |
| authors | The person(s) primarily responsible for the creation of the data |
| product_type | The product type of the record (one of "Dataset" or "Collection") |
| doi | The Digital Object Identifier (DOI) |
| publication_date | The publication date, in ISO-8601 format |
| announcement_date | The announcement date, in ISO-8601 format |
| publisher | The name of the entity that holds, archives, distributes, releases, or produces the resource |
| country_publication | The country in which this version of the record was published |
| format | Additional format / paging information |
| language | The primary language of the resource |
| availability | If applicable, the office or organization to refer access requests to |
| research_org | If credited, the organization name primarily responsible for conducting the research |
| sponsor_org | If credited, the organization name that sponsored / funded the research |
| submitting_site | If credited, the organization name that submitted the research |
| subjects | A list of subjects, keywords, or key phrases describing the resource |
| doe_contract_number | The DOE contract number associated with the entry |
| other_identifying_numbers | Other ID number that can be used to find the record |
| report_number | The report number associated with the entry |
| entry_date | The date the record was added or last modified, in ISO-8601 format |
| links | Full URL's to the citation and the full text for this OSTI ID |
HTTP/1.1 200 OK
Content-Type: application/json[
{
"article_type":null,
"osti_id":"{osti id}",
"subjects":[
],
"format":"Medium: ED",
"announcement_date": "2017-03-21T03:22:47.744Z",
"description":"Cras ac lacinia quam, ac viverra mauris. Duis aliquam blandit nibh",
"doe_contract_number":"AC04-94AL85000",
"language":"English",
"availability":"",
"title":"Pellentesque ornare velit id enim hendrerit eleifend. Praesent facilisis",
"entry_date":"2017-03-23T04:00:00Z",
"product_type":"Patent",
"report_number":"9,603,210",
"country_publication":"United States",
"publication_date":"2017-03-21T04:00:00Z",
"publisher":"",
"sponsor_orgs":[
"Lorem ipsum"
],
"links":[
{
"rel":"citation",
"href":"https://www.osti.gov/etdeweb/biblio/{osti id}"
},
{
"rel":"fulltext",
"href":"https://www.osti.gov/etdeweb/servlets/purl/{osti id}"
}
],
"other_identifying_numbers": "TRN: US201016%%2115",
"submitting_site": "ETTP",
"research_orgs":[
" Aenean at mi vulputate (Irem), faucibus ipsum a, tempor ipsum (Icorus). "
],
"doi":"https://doi.org/{doi}",
"authors":[
"Cras, ac lacinia"
]
}
]HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<records>
<record>
<osti_id>{osti id}</osti_id>
<title>High speed, high current pulsed driver circuit</title>
<description>Cras ac lacinia quam, ac viverra mauris. Duis aliquam blandit nibh</description>
<authors>
<author>Cras, ac lacinia</author>
</authors>
<product_type>Patent</product_type>
<doi>https://doi.org/{doi}</doi>
<publication_date>2017-03-21T04:00:00Z</publication_date>
<publisher />
<country_publication>Italy</country_publication>
<format>Medium: ED</format>
<language>English</language>
<availability />
<research_orgs>
<research_org>Aenean at mi vulputate (Irem), faucibus ipsum a, tempor ipsum (Icorus)</research_org>
</research_orgs>
<sponsor_orgs>
<sponsor_org>USDOE</sponsor_org>
</sponsor_orgs>
<submitting_site>ETTP</submitting_site>
<subjects />
<doe_contract_number>AC04-94AL85000</doe_contract_number>
<report_number>9,603,210</report_number>
<other_identifying_numbers>TRN: US201016%%2115</other_identifying_numbers>
<entry_date>2017-03-23T04:00:00Z</entry_date>
</announcement_date>2010-08-18T03:22:47.744Z</announcement_date>
<links>
<link rel="citation" href="https://www.osti.gov/etdeweb/biblio/{osti id}" />
<link rel="fulltext" href="https://www.osti.gov/etdeweb/servlets/purl/{osti id}" />
</links>
</record>
</records>
HTTP/1.1 200 OK
Content-Type: application/x-bibtex@misc{dataset-id,
title = {Mastering the ETDEWEB 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,
}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.
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 |
Errors are always presented as a single object, formatted according to the content type requested.
| Error Fields | |
|---|---|
| Field Name | Description |
| statusCode | The response error code, duplicated for convenience |
| statusMessage | A brief description of the error type |
| errorDescription | A more detailed description of the specific error cause |
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" encoding="UTF-8"?>
<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-bibtex404
Not Found
No record matching the supplied OSTI ID was foundThe ETDEWEB 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.
https://www.osti.gov/etdeweb/api/v1GET /records
The record list endpoint allows you to search for lists of records in ETDEWEB by a variety of criteria.
| Record List Query Parameters | |
|---|---|
| Parameter | Description |
| q | General query field, will search full record for provided terms |
| osti_id | The unique OSTI identifier for a record |
| fulltext | Searches the article full text (if available) for the provided terms |
| biblio | Searches the bibliographic information for the provided terms |
| author | Searches the author entries |
| title | Searches within document titles |
| doi | Finds records based on common doi (report number, contract number, etc.) |
| identifier | Finds records based on common identifiers (report number, contract number, etc.) |
| sponsor_org | Searches the sponsoring organization field |
| research_org | Searches the research organization field |
| contributing_org | Searches the contributing organization field |
| source_id | A code specifying the organization that submitted the record |
| publication_date_start | Beginning publication date boundary in MM-DD-YYYY format |
| publication_date_end | End publication date boundary in MM-DD-YYYY format |
| entry_date_start | Beginning entry date boundary in MM-DD-YYYY format |
| entry_date_end | Ending entry date boundary in MM-DD-YYYY format |
| language | Finds records by language |
| country | Finds records by country of publication |
| sort | Specifies a field name on which to sort |
| order | Specifies the sort order (one of asc or desc) |
| rows | The number of rows per page to return (default 20) |
| page | The specific page of records to return (default 1) |
https://www.osti.gov/etdeweb/api/v1/recordsGET /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.
https://www.osti.gov/etdeweb/api/v1/records/{osti_id}The ETDEWEB 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.