Table of Contents


Use the eScholarship API to query for Items (publications), Authors, and Units (journals, series, departments / research units) within eScholarship.org, returned as JSON. The API uses the GraphQL query language.

GraphiQL implementation

https://escholarship.org/graphql 

This web based IDE provides a tabbed interface for editing and testing GraphQL queries against the eScholarship API. The Documentation Explorer allows you to drill down into each object, its fields, and arguments.

Type Definitions

Refer to this single page outline for a flat list of all queryable objects: https://github.com/eScholarship/escholApi/blob/master/lib/schema.graphql

Simple Examples

Get all eScholarship items (default: first 100 listed, ordered by most recently added):

{
  items{
    nodes {
      title
      permalink
    }
  }
}

GraphiQL: https://goo.gl/TnwnqH

Get an eScholarship item using a DOI:

{
  item(id: "10.3945/jn.114.202333", scheme: DOI) {
    permalink
    title
    journal
    volume
    issue
    issn
  }
}

GraphiQL: https://goo.gl/6rnxuu

Note that the primary id for an Item is an ARK ID. The above example is a query using a alternative identifier scheme: e.g specifying item(id: "ark:/13030/qt01r1171s") points to the same Item.

Item Data

The Item query provides the richest amount of data of all the objects, including:

  permalink - the page where the item and corresponding metadata resides on eScholarship: i.e. https://escholarship.org/uc/item/65k8r3bd

 contentLink  - the download link for PDF/content file (if applicable)

Explore the GraphiQL implementation and type definition outline to see all fields available.

Pagination

Arrays of objects (Authors, Contributors, Items, and Units) are delivered using the nodes field. These object arrays can also be accompanied in the selection set with the following utilitarian fields describing the set:

 total - Approximate count of all objects that can be returned

 more - Opaque cursor string for next page, if total exceeds limit (set to 100 by default)

The results of the following query include the cursor string more that is used to retrieve the next page of 10 results:

{
  unit(id: "ucsdecon_rw") {
    name
    items (first: 10) {
      total
      more
      nodes {
        permalink
        title
      }
    }
  }
}


GraphiQL: https://goo.gl/8M8ZVY

To retrieve the next page of results, query again. This time, embed the string provided by the more field into the more argument for items. Do not specify any other arguments with this one; the string already encodes the prior set of arguments (in this example, first: 10 should be removed in next query). Each query using a more argument provides a new cursor string for the following page. If it has reached the end, the returned more value will be null.

{
  unit(id: "ucsdecon_rw") {
    id
    name
    items (more: "eyJmaXJzdCI6MTAsIm9yZGVyIjoiQURERURfREVTQyIsImxhc3RJRCI6InF0MWZ6MTc4NDciLCJsYXN0RGF0ZSI6IjIwMTYtMDMtMTEifQ"){
      total
      more
      nodes {
        permalink
        title
      }
    }
  }
}

GraphiQL: https://goo.gl/Smdheh

More Example Queries

Get the title, published date and authors for all the Items in a Unit:

{ 
  unit(id: "lmri_pr") {
    id
    name
    items {
      nodes {
        title
        permalink
        published
        authors {
          nodes{
            name
          }
        }
      }
    }
  }
}

GraphiQL: https://goo.gl/JFWguF

Get the first 50 Items with a certain “tag” (i.e. keyword or subject) within a given Unit:

{
  unit(id: "lbnl") {
    id
    name
    items (first: 50, tags: "subject:Environmental sciences"){
      total
      more
      nodes {
        title
        permalink
        subjects
      }
    }
  }
}

GraphiQL: https://goo.gl/ZyT8TE

Get all the Items associated with an Author (exact for now, fuzzy in the future):

{
  author(email: "lisa.schiff@ucop.edu") {
    id
    name
    items {
      total
      nodes {
        id
        title
      }
    }
  }
}

GraphiQL: https://goo.gl/C7Z29L

Get all the Items of a certain type:

{
  items (tags: "type:CHAPTER"){
    total
    nodes {
      bookTitle
      title
      permalink
      published
    }
  }
}

GraphiQL: https://goo.gl/cykLsy

Get all the Items published between certain dates:

{
  unit(id: "ucd") {
    name
    items (after: "2017-01-01", before:"2017-12-31", order: PUBLISHED_DESC) {
      total
      more
      nodes {
        permalink
        title
        published
      }
    }
  }
}

GraphiQL: https://goo.gl/28m4U3

Get an Item using an an Elements ID:

{ 
  item(id: "709820", scheme: OA_PUB_ID) {
    id
    title
    journal
    volume
    issue
    issn
  }
}

GraphiQL: https://goo.gl/iFYZWf

Ruby Example

require 'httparty'

query = "{ items(first:5) { nodes { title permalink } } }"

result = HTTParty.post("https://escholarship.org/graphql",
           :headers => { 'Content-Type' => 'application/json' },
           :body => { "query" => query }.to_json)
result.code == 200 or raise "HTTP error #{result.code}: #{result.body}"
result['errors'] and raise "GraphQL error: #{result['errors']}"

puts JSON.parse(result.body)['data']

Python Example

import requests
import json

query = "{ items(first:5) { nodes { title permalink } } }"

response = requests.post('https://escholarship.org/graphql',
             headers = { 'Content-Type': 'application/json' },
             data = json.dumps({ 'query': query }))
if response.status_code != 200:
  raise Exception("HTTP error %d: %s" % (response.status_code, str(response.content)))
if 'errors' in response.json():
  raise Exception("GraphQL error: " + str(response.json()['errors']))

print(response.json()['data'])

Code of Conduct

Please do not abuse the API with thousands of requests per hour for hours at a time. API abusers may be throttled or cut off.

Feedback

We'd love to hear how you're making use of the eScholarship API - please share your story with us!