Using the eScholarship OAI-PMH Interface

Modified on Mon, Jan 9, 2023 at 3:27 PM

eScholarship is compliant with the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH), which means that metadata about the publications in eScholarship are discoverable via our OAI-PMH interface. Information can be gathered manually through web requests submitted in a browser or it can be harvested programmatically.

Below are some OAI-PMH example URL requests for eScholarship.

Base URL

Every OAI-PMH interface has a base URL, which serves as the root for all OAI-PMH requets. The base URL for eScholarship's OAI-PMH interface is: 

https://escholarship.org/oai

Note that we currently support both http and https.

The base URL cannot be used on its own, but must have a valid OAI-PMH verb following it. A few of these are described below.

Getting All Records Within a Set

Each campus, unit and series within eScholarship has a set in our OAI-PMH interface.  After determing which set(s) are of interest, a request can be made to get all of the records in that set. Below is a URL which will return all of the metadata records for the paper series Retention Report Series from the UCLA Institute for Democracy, Education, and Access.

https://escholarship.org/oai?verb=ListRecords&metadataPrefix=oai_dc&set=idea_rrs

Note that any requests for one or more records must include the "&metadataPrefix=oai_dc" parameter. The value of that parameter may be different at other sites supporting OAI-PMH.

Listing All Records

Sometimes there is an interest in getting a list of all records, however eScholarship, and most OAI-PMH compliant resources, contain too many records to return in a single page of results. Because of this, a "resumptionToken" must be used after the first request, in order to page through the entire set of records. The resumptionToken is the value in the <resumptionToken> element at the bottom of each "ListIdentifiers" results page.    

To  capture all of the records:

  1. Issue an initial "ListRecords" request:
    https://escholarship.org/oai?verb=ListRecords&metadataPrefix=oai_dc 
    At the bottom of that page will be a <resumptionToken /> element, as in the example below:
    <resumptionToken expirationDate="2018-05-04T17:50:11Z" cursor="0" completeListSize="197890">oai_dc::500:197890:eyJmaXJzdCI6NTAwLCJvcmRlciI6IlVQREFURURfREVTQyIsImxhc3RJRCI6InF0OTBmOG0ycWgiLCJsYXN0RGF0ZSI6IjIwMTgtMDQtMzBUMTE6MTA6MjMtMDc6MDAifQ</resumptionToken>
  2. Issue subsequent requests using the resumptionToken value from each results page for the next request, e.g. https://escholarship.org/oai?verb=ListRecords&resumptionToken=oai_dc::500:197890:eyJmaXJzdCI6NTAwLCJvcmRlciI6IlVQREFURURfREVTQyIsImxhc3RJRCI6InF0OTBmOG0ycWgiLCJsYXN0RGF0ZSI6IjIwMTgtMDQtMzBUMTE6MTA6MjMtMDc6MDAifQ

Getting a Single Record

Listing all of the record identifiers allows the retrieval of the metadata records for each item. Below is a URL that will return the record for an item after discovering its identifier through a "ListIdentifiers" request.

https://escholarship.org/oai?verb=GetRecord&metadataPrefix=oai_dc&identifier=qt1x12d5zc