OAI-PMH Service

Publication Details

Estimated reading time: 3 minutes

The NCBI Bookshelf OAI-PMH service (Books-OAI) provides access to metadata of all items in the Bookshelf archive, as well as to the full text of a subset of these items.

Books-OAI is an implementation of the Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH), a standard for retrieving metadata from digital document repositories. Visit the Open Archives Initiative site for more information about the protocol and other activities of the OAI group.

Books-OAI supports OAI-PMH version 2.0. It does not support earlier versions of the protocol.

If you have questions or comments about this, or any of the other services provided by the NCBI Bookshelf, please write to vog.hin.mln.ibcn@flehskoob.

Copyright

Most of the items in this archive are copyright protected, with copyright held by the author(s) or the depositing publisher. In general, the OAI service cannot be used to retrieve the full text of documents in the NCBI Bookshelf. The only exceptions to this policy are for documents that are in the public domain and those that are made available under an Open Access provision (as defined in the Open Access Subset). See the Bookshelf Copyright Notice for more information.

Using the Books-OAI Service

The base URL for the service is https://api.ncbi.nlm.nih.gov/lit/oai/books/.

See the examples, below, for details about how to use this service to retrieve metadata for books and documents.

High-Volume Retrievals

If you are using a script that makes more than 100 requests of any kind, please run it outside of the Bookshelf system's peak hours. Also, please make sure that your system does not make concurrent requests, even at off-peak times. Peak hours are Monday to Friday, 5:00 AM to 9:00 PM, U.S. Eastern time.

The Books-OAI Service supports HTTP compression, and the Accept-Encoding HTTP header must be set to 'gzip, deflate' for the most efficient data transfer. See also HTTP compression for further information about this capability.

Access to Full Text

Some Bookshelf participants allow harvesting of the full text of all items, others allow it for only some items, and many do not allow it at all. See the Open Access Subset for specifics.

In addition, the parameter set=book-open identifies the complete collection of items in Bookshelf for which the full text may be harvested.

Supported Data Formats

Records may be retrieved from the Bookshelf archive in either the “NCBI Book Tag Set” or the “Book Interchange Tag Set” XML format for metadata or full-text book records. A DTD, W3C Schema, and complete documentation for these formats are available from https://dtd.nlm.nih.gov and from https://jats.nlm.nih.gov/extensions/bits/. The prefixes are:

• Metadata: metadataPrefix=nbk_meta

• Full Text: metadataPrefix=nbk_ftext

OAI Books identifiers

The identifiers used by this system are of the form:

oai:books.ncbi.nlm.nih.gov:nbkid

where nbkid is the numerical portion of the document’s accession ID. For example, the OAI identifier for the document NBK315783 is oai:books.ncbi.nlm.nih.gov:315783.

Automatic Segmentation of Large Result Sets

If a ListIdentifiers request results in more than 500 hits, Books-OAI will return the first 500 with a <resumptionToken> that can be used to get the remaining items.

If a ListRecords request results is more than 25 hits for full text or 50 hits for metadata, Books-OAI will return the first 25, or 50 records, respectively, with a <resumptionToken>.

Examples

Identify

ListMetadataFormats

ListIdentifiers – return a fixed number of identifiers per request.

Typically, the response to this request will contain 500 identifiers, and will include a resumption token at OAI-PMH/ListSets/resumptionToken.

ListRecords – return a fixed number of records per request.

Typically, the response will contain 25 full-text XML records.

ListSets – return a fixed number of sets per request

GetRecord – retrieve a record by identifier