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 OAI-PMH URL
Every OAI-PMH interface has a base URL, which serves as the root for all OAI-PMH requests. The base URL for eScholarship's OAI-PMH interface is:
eScholarship 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.
Sets and obtaining all records within a set
Each campus, unit, and series within eScholarship has a set in our OAI-PMH interface. The set's ID is the campus, unit, or series slug, which is found at the end of its URL in eScholarship. For example:
- Campus URL: https://escholarship.org/uc/ucr
- Series URL: https://escholarship.org/uc/idea_rrs
After identifying the set of interest, a request can be made to get all of the records in that set in the format:
- https://escholarship.org/oai?verb=ListRecords&metadataPrefix=oai_dc&set=[set ID/slug]
The below call returns all metadata records for the Retention Report Series from the UCLA Institute for Democracy, Education, and Access:
- Series URL: https://escholarship.org/uc/idea_rrs
- 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.
List 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:
- 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> - 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
Obtain 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