OAI - overview
OAI (Open Archives Initiative) is an initiative aimed at defining an open interface for the exchange of metadata. Communication in such an interface takes place between the German National Library as the data provider and a service provider requesting the data. The data is collected automatically by an "OAI harvester". The protocol used for the communication is called OAI-PMH (OAI-Protocol for Metadata Harvesting). OAI permits continuous synchronisation of large amounts of data; this is based on the import of data from an up-to-date basic stock to a separate database.
Following login and authorisation, the German National Library allows its data to be searched using an HTTP or HTTPS interface and the OAI-PMH protocol.
- Standard of the OAI interface
- OAI-PMH Protocol
- OAI harvester
- OAI functions
- German National Library catalogues (sets) accessible via OAI
- Formats
- Test access / Access requirements
- Conditions and costs
- Contact
- Practical examples
Frequently Asked Questions (FAQ) / Troubleshooting
Standard of the OAI interface
Protocol: OAI-PMH Version 2.0
OAI-PMH Protocol
The OAI-PMH protocol is web-based. The OAI harvester works with simple requests using HTTP-GET or -POST and receives an HTTP response back from the data provider. Embedded in an XML structure, this response contains the requested metadata. An advantage is that an OAI repository can be searched even with a web browser.
OAI harvester
In order to use OAI to compare the data between the German National Library and a service provider, the service provider must have implemented an OAI harvester (e. g. OAI-PMH Harvester Manager) The OAI harvester calls itself repeatedly in a continuous loop. It executes a "ListRecords command" limited to the dataset (catalogue) defined for the service provider. In addition, the „ListRecords-command“ is given the time of the last call in the form of a Time stamp.This ensures that
- no change is missed
- changes are shown with minimum delay in the service provider's database
- no data which is irrelevant for the service provider is transported
OAI functions
The OAI-PMH protocol includes six basic functions which are appended to the baseURL (e.g. "http://services.dnb.de/oai/repository") using "?verb=":
Identify: Display general information about OAI repository, e.g.
- repositoryName
- baseURL
- protocolVersion
ListSets: Information about all data sets (catalogues) available in OAI repository
ListMetadataFormats: List of all data formats available in OAI repository
GetRecord: Call of individual data records using the ID. The identification number of the data record concerned must be known for this
Parameter:
- identifier: Identification number of required data record
- metadataPrefix: Name of the data format in which the data record is to be issued. The selection of values can be requested using the ListMetadataFormats command (see above).
ListRecords: Harvest data records by entering the time period (from / until) and/or data sets. This is the core command of OAI. It permits selective harvesting, i.e. the harvester can restrict the request to data records which
- originate from a particular catalogue and
- were created or changed in a particular period
The time is given in UTC.
Parameter:
- from / until: Points which define the time period for the selective harvesting. Depending on the OAI repository these can be either defined to the day (YYYY-MM-DD) or to the second (YYYY-MM-DDThh:mm:ssZ)
- set: The catalogue from which the data records originate
- metadataPrefix: see above
- resumptionToken: Permits the return of part responses. The OAI harvester is sent a token which he can use for a new request to obtain the next responses from the OAI repository. The token sends back details of the date of expiry, the size of the total list and counter (optional).
German National Library catalogues (sets) accessible via OAI
| Catalogue selection | Value for "set" parameter |
|---|---|
| Catalogue of the German National Library (DNB), without "Gemeinsame Normdatei" (GND) | dnb |
| Catalogue of the German National Library (DNB) with New Release Service (ND) and without "Gemeinsame Normdatei" (GND) | dnb-all |
| Restricted to subject class | dnb:sg020 (example of library and information science) |
| Restricted to bibliography series | dnb:reiheA (example) |
| Restricted to subject class | dnb:reiheA:sg720 (example of architecture) |
| DNB online publications | dnb:online |
| Restricted to subject class | dnb:online:sg020 (example of library and information science) |
| DNB online dissertations | dnb:online:dissertations |
| Restricted to subject class | dnb:online:dissertations:sg720 (example of architecture) |
| Catalogue of "Gemeinsame Normdatei" (GND) | authorities |
Formats
The following formats are offered in Changes to UTF-8 character set (PDF, 25KB, Not barrier-free file.):
| MARC 21-XML Example | XML variant of MARC 21 | http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd |
| MABxml-1 Example | XML variant of MAB2 only for bibliographic data, Provision ends on 30 June 2013 | Schema-Definition |
| DNB Casual (oai_dc) Example | Selection of Dublin-Core elements only for bibliographic data | http://www.openarchives.org/OAI/2.0/oai_dc.xsd |
| RDFxml Example | Linked Data Service | http://www.w3.org/2000/07/rdf.xsd |
Test access / Access requirements
You can use the OAI interface for free in a 4-week test phase.
To do so, please send a mail containing your contact details and a fixed IP address or IP-range, catalogue and desired format to the Interface Service. Alternatively it is also possible to obtain access via an individual access code (access token). We will contact you as soon as possible to clarify any unresolved issues and to request any additional data which is required.
Following a successful test run you will be sent the agreement forms for accessing charged data on request.
Conditions and costs
During the test phase, use of the OAI interface is free of charge via the OAI interface.
Afterwards a charge may be levied, depending on the selected set and the required data format.
Authority data is supplied free of charge, so too is bibliographic data on online publications (Series O der Deutschen Nationalbibliografie) Also free of charge is the use of all data in RDFxml format and bibliographic data in DNB Casual (Selection of Dublin Core elements), see also the business model for use of data services of the German National Library. A fee is payable for all other formats when using bibliographic data from series A, B, C, H, M and T.
The following annual fees are charged (EUR) (valid from 1 July 2012):
| Series | Content | Formats MARC 21-XML and MABxml-1 | Formats DNB Casual and RDFxml |
|---|---|---|---|
| Series A | Publishing trade publications | 2,805.00 | free of charge |
| Series B | Publications not from publishing trade | 1,734.00 | free of charge |
| Series C | Maps | 204.00 | free of charge |
| Series H | University publications | 756.00 | free of charge |
| Series M | Printed music (probably available in the end of 2013) | 240.00 | free of charge |
| Series O | Online-Publikationen | free of charge | free of charge |
| Series T | Sound recordings (probably available in the end of 2013) | 516.00 | free of charge |
| New Release Service | Publisher announcements regarding future and new publications to VLB | 918.00 | free of charge |
| GND | Integrated Authority File | free of charge | free of charge |
For those requesting individual series, access via the OAI interface to subscribed series is free, i.e. is included in the subscription price.
For submitters of online publications, access to metadata they themselves have submitted is free of charge via the OAI interface. Here, the ID of the submitter needs to be added to the "dnb:online" set request: ":dyn:ido:<ID of submitter>". In this case the metadata format is freely selectable.
Special arrangements have been agreed for library networks and service centres. The commercial use of charged bibliographic data (except for CC0 conditions) is subject to separate agreements.
Contact
| Interface Service | Monday - Friday from 9.00 a.m. to 3.00 p.m. |
| Nicole von der Hude | Tel.: +49-69-1525-1632 |
| Heike Eichenauer | Tel.: +49-69-1525-1074 |
Practical examples
Syntax of an OAI request
| Example | Explanation |
|---|---|
| http://services.dnb.de/oai/repository https://services.dnb.de/oai/repository | Request to OAI server of the German National Library |
| ?verb=ListIdentifiers | Command to server |
| &from=2012-04-23 | Parameter &from defines the start of the query period |
| &until=2012-04-24 | Parameter &until defines the end of the query period |
| &metadataPrefix=MARC21-xml | Format desired for OAI reply |
| &set=authorities | Defines the catalogue or set |
Syntax of an OAI request with a specific ID number
http://services.dnb.de/oai/repository?verb=GetRecord&metadataPrefix=MARC21-xml&identifier=oai:dnb.de/authorities/118540238
Syntax of an OAI request for online dissertations from the "Social sciences, sociology, anthropology" subject class within a specific time period
http://services.dnb.de/oai/repository?verb=ListRecords&from=2012-04-01T14:55:00Z&until=2012-07-08T09:54:59Z&metadataPrefix=oai_dc&set=dnb:online:dissertations:sg300
Number of data records returned per request
The hit list is limited to 100,000 data records. An error message is issued if the hit list is larger than this.
Last update: 3.6.2013
