eScholarship Public (Read) API

Table of Contents

• Terms of Use
• GraphiQL implementation
• Queryable Objects
• Simple Examples
• Item Data
• Pagination
• More Example Queries
• Writing Data
• Ruby Example--Retrieve First 5 Items
• Ruby Example--Using Pagination To Retrieve All Items
• Python Example
• Feedback

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.

Terms of Use

Use of the eScholarship Public (Read) API must abide by the eScholarship API Terms of Use. Please do not abuse the API with thousands of requests per hour for hours at a time. Users who make excessive API requests that compromise service quality may be throttled or cut off.

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.

Queryable Objects

The IDE is also where to find the set of queryable objects.  Click on the "Docs" link in the upper right hand corner to search for objects and their components and attributes.

Simple Examples

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

{
  items{
    nodes {
      title
      permalink
    }
  }
}

GraphiQL

Get an eScholarship item using a DOI:

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

GraphiQL

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 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

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

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

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

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

{
  author(email: "[email protected]") {
    id
    name
    items {
      total
      nodes {
        id
        title
      }
    }
  }
}

GraphiQL

Get all the items of a certain type:

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

GraphiQL

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

Determine when an item first appeared on eScholarship

{
  item(id: "ark:/13030/qt3dw6f08j") {
    id
    title
    journal
    volume
    issue
    issn
    added
  }
}

GraphiQL

Get an item using a UCPMS ID:

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

GraphiQL

Get the date of expiry of an embargo of a thesis or dissertation:

{
  item(id: "ark:/13030/qt2k3957sr") {
    id
    title
    type 
    added
    embargoExpires
  }
}

GraphiQL

Writing Data

The eScholarship API also allows writing data using QraphQL’s mutations, including the ability to create, replace, or withdraw items. See the mutation root type in the GraphiQL implementation for more details.

Ruby example : retrieve first five items

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']

Ruby example : use pagination to retrieve all items

require 'httparty'

more = "null"
loop do
        query = "{unit(id: \"vertebrate_pest_conference\"){ id name items (more:#{more}) {total more nodes { 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']

        data = JSON.parse(result.body).dig('data', 'unit','items')
        more = data.dig('more')
        #print ARKS
        data['nodes'].each {|item|
          puts "#{item['permalink']}"
        }
        break if ! more
        more = "\"" + more + "\""
end

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'])

Feedback

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