Using the eScholarship OAI-PMH Interface

Modified on Mon, 09 Jan 2023 at 03: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:

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.

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

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.