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.
- eScholarship base URL
- Listing Sets
- Getting All Records Within a Set
- Listing All Records
- Getting a Single Record
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/uc/oai.
The base URL cannot be used on its own, but must have one of the six valid OAI-PMH verbs following it. A few of these are described below.
Sets are sub-groupings of records as defined by the resource. They can be based on author names, subject metadata, or any other feature a resource provider feels is useful. eScholarship currently provides sets based on academic discipline and unit within eScholarship.
All of the sets that are available in a resource can be discovered by using the "ListSets" verb. Below is a URL that when clicked will show all of the sets available in eScholarship.
After determing which set(s) are of interest, another 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.
Sometimes there is an interest in getting a list of all records. This can be done by using the "ListRecords" verb, as with the URL below.
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. Below is an example of a request made to get the second page of results from eScholarship (note that eScholarship resumptionTokens include unescaped characters):
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.