EZB OA API
Link to the interface: https://ezb.ur.de/api/oa_rights
1. What is the OA-EZB interface?
Alliance, national or consortium licences often contain Open Access (OA) rights for secondary publication of full texts (e.g. via a repository). The OA-EZB Interface makes the OA rights stored in the EZB available for free subsequent use.
The OA rights from alliance, national and consortium licences provided in this interface are stored in the EZB by package administrators (who are usually also the negotiators). They also maintain the participating institutions belonging to the licence including the corresponding journal titles in the EZB.
2. Which formats can be issued?
The output of the requested data can be in either JSON or XML. The interface user sets the parameter format to either application/json or application/xml.
3. Interface 1: General output of Open Access rights (OA rights)
Based on the parameters package_id or collection_id provided, all OA rights stored for the corresponding package or collection in the EZB are issued in general.
3.1 Transfer parameters
The following parameters can be transferred to the interface:
| Transfer parameters | Values | Default value | Explanation |
|---|---|---|---|
| lang | ‘de’ and ‘en’ | ‘de’ | [optional] language |
| package_id | [A-Z0-9]{3,5} | – | [mandatory selection a*] Package ID. Either package_id or collection_id must be transferred. |
| collection_id | ‘EZB-XXXX-00000’ | – | [mandatory selection b*] EZB identifier. Either package_id or collection_id must be transferred |
| format | ‘application/xml’ and ‘application/json’ | – | [mandatory] Format of the data output. |
*mandatory selection means that one of the mentioned parameters must be transferred.
3.2 Output panels
The OA rights can be deposited for an entire EZB journal package (e.g. Allianz licence package). If separate OA rights apply to certain collections or journal titles, these can be entered separately at collection or journal title level. When an issue is made, the OA rights are hierarchically structured according to package, collection and journal level.
The following fields form the data output of the interface:
| Field | Field Description |
|---|---|
| oa_level | Field to output the level at which OA rights were granted. The oa_level can be either ‘package’ (OA rights assignment at package level), ‘collection’ (separate OA rights assignment at collection level) or ‘journal’ (separate OA rights assignment at journal level). The output is hierarchical. |
| oa_lfnr | Sequential number of the OA right (internal identifier) |
| oa_first_date | Start period with OA rights |
| oa_last_date | End period with OA rights |
| oa_embargo_months | Indication of the period in months to be taken into account until the second publication can be issued |
| oa_pub_authority | Indication of who has the right of secondary publication, e.g. author |
| oa_archivable_version | Specifies which version of the publication may be secondarily published, e.g. pre-print document |
| oa_repositories | Indication of where the secondary publication can be placed, e.g. author’s website |
| oa_source | Indication of the source from which the publication for secondary publication must come, e.g. reference via author |
| remarks_de | Notes on OA rights in German |
| remarks_en | Notes on OA rights in English |
| oa_last_change | Date of last change |
3.3 Examples
Query of the OA rights for the journal package with the EZB package ID ‘NALIX’
Which OA rights are registered for the German National License ‘Walter de Gruyter Online-Zeitschriften Archiv’ with the EZB package ID ‘NALIX’? On which levels are OA rights registered?
https://ezb.ur.de/api/oa_rights?lang=en&package_id=NALIX&format=application/json
Query of the OA rights stored for the collection with the collection ID ‘EZB-NALIX-00498’
Which OA rights are registered for the collection ‘Walter_en_Gruyter_Online-Zeitschriften_Archiv_NL’ with the EZB collection ID ‘EZB-NALIX-00498’? At which levels have OA rights been stored?
https://ezb.ur.de/api/oa_rights?lang=en&collection_id=EZB-NALIX-00498&format=application/json
4. Interface 2: Institution and journal-specific output of Open Access rights (OA rights)
The parameters bibid, issn, doi, title and/or year are used to check whether OA rights from alliance, national or consortium licences have been deposited at the EZB for the requested article in the relevant library.
Example query:
https://ezb.ur.de/api/oa_rights?bibid=UBR&issn=1938-2650&year=2013&format=application/json
4.1 Transfer parameters
The following parameters can be transferred to the interface:
| Transfer parameters | Values | Default value | Description |
|---|---|---|---|
| lang | ‘de’ and ‘en’ | ‘de’ | [optional] Language of the data output |
| bibid | [A-Z0-9]{3,5} | – | [mandatory] EZB identifier of the institution for which the OA rights are requested |
| year | e.g. 2018 or 2018-12-11 | – | [optional] year or date ‘Y-m-d’ of a resource for which OA rights are requested |
| issn | ‘XXXX-XXXX’ or ‘XXXXXXXXX’ | – | [mandatory selection a*] eISSN or pISSN of a journal for which OA rights are requested |
| doi | e.g. ‘10.1000/xyz123’ | – | [mandatory selection b*] Digital Object Identifier (DOI) of a resource for which OA rights are queried |
| title | ‘The sample journal’ | – | [mandatory selection c*] Title of a journal for which OA rights are requested |
| format | ‘application/xml’ and ‘application/json’ | – | [mandatory] Format of the data output |
*Mandatory Selection means that one of the mentioned parameters must be passed. If the ISSN is passed, the other mandatorily selective parameters are no longer necessary.
4.2 Output fields
The following fields form the data output of the interface:
| Field | Field Description |
|---|---|
| state | Field for the output of the status code The definition of all status codes is listed under 4.3. |
| message | Field for outputting the status code in text form |
| institution_id | EZB-BIBID of the requested institution |
| institution_name | Name of the requested institution |
| issn | ISSN of the requested journal |
| oa_agreement | Name of the licence containing the issued OA right |
| oa_package_name | EZB package ID of the licence containing the issued OA right |
| oa_lfnr | Sequence number of the OA right (internal identifier) |
| oa_level | Field to output the level at which OA rights have been assigned (assignment possible at package, collection and journal level) |
| oa_first_date | Start period with OA rights |
| oa_last_date | End period with OA rights |
| oa_embargo_months | Indication of the period in months to be taken into account until the secondary publication can be issued |
| oa_pub_authority | Indication of who has the right of secondary publication, e.g. author |
| oa_archivable_version | Specifies which version of the publication may be secondarily published, e.g. pre-print document |
| oa_repositories | Indication of where the secondary publication can be placed, e.g. author’s website |
| oa_source | Indication of the source from which the publication for secondary publication must come, e.g. reference via author |
| remarks_de | Notes on OA rights in German |
| remarks_en | Notes on OA rights in English |
4.3 Status messages
The following table provides an overview of the possible status messages that can be generated by the interface.
| Status Code | Status Message(DE=German) | Status Message (EN=English) |
|---|---|---|
| 0 | OA-Verwertungsrechte vorhanden. | OA rights available. |
| 1 | Es sind OA-Verwertungsrechte für den angefragten Zeitraum hinterlegt | OA rights available for the requested period. |
| 2 | Für Ihre Anfrage sind keine OA-Verwertungsrechte in der EZB hinterlegt | No OA rights available. |
| 3 | Es sind keine OA-Verwertungsrechte für den angefragten Zeitraum in der EZB hinterlegt | No OA rights available. |
| 3 | Es sind keine OA-Verwertungsrechte für den angefragten Zeitraum in der EZB hinterlegt | No rights available for the requested period. |
| 4 | ISSN von OA-Klausel ausgeschlossen. | ISSN excluded from OA right. |
| 5 | Zu dieser DOI konnte keine passende ISSN gefunden werden | No matching ISSN could be found for this DOI. |
| 6 | Zu diesem Zeitschriftentitel konnte keine passende ISSN gefunden werden | No matching ISSN could be found for this journal title. |
| 7 | – | – |
| 8 | Für Ihre Anfrage sind keine OA-Rechte in der EZB hinterlegt | No entries could be found for this ISSN in the EZB. |
| 9 | Für Ihre Anfrage sind keine Informationen in der EZB hinterlegt | There is no information provided in the EZB for your request. |
4.4 Examples
Query using the ISSN, XML output
Query using the ISSN, XML output Are OA rights available for the journal with the ISSN 1938-2650 at the University Library Regensburg (EZB-BIBID: UBR) for the year 2016?
https://ezb.ur.de/api/oa_rights?bibid=UBR&issn=1938-2650&year=2016&format=application/json
Query using DOI, JSON output
Are OA rights available for the journal article with the DOI 10.1159/000447733 
at the University Library Regensburg (EZB-BIBID: UBR)? The data output should be in English and as JSON.
https://ezb.ur.de/api/oa_rights?bibid=UBR&doi=10.1159/000447733&lang=en&format=application/json
Search by journal title
Are OA rights available for the journal ‘Aggression and Violent Behavior’ at the University Library Regensburg (EZB-BIBID: UBR) for the year 2018?
https://ezb.ur.de/api/oa_rights?bibid=UBR&title=Aggression%20and%20Violent%20Behavior&year=2018&format=application/json
5. Which output options are available?
The following fields have standardized, multi-optional outputs:
| Field | German | English |
|---|---|---|
| oa_level |
|
|
| oa_pub_authority |
|
|
| oa_archivable_version |
|
|
| oa_repositories (Output of several options possible) |
|
|
| oa_source (Output of several options possible) |
|
|
6. How to integrate Open Access (OA) rights into institutional repositories?
OA rights that have been deposited at the EZB can, for example, also be integrated into institutional repositories. A plug-in has been developed for EPrints repositories. It consists of three modules that can be configured separately. The first module accesses the OA-EZB interface and displays an overview of the information on secondary publication rights stored in the EZB, e.g. for Alliance licences. The second module accesses publisher-side OA policies in SHERPA/RoMEO. In the third module a reference to the German secondary publication rights according to the German Copyright Act is displayed. In the frontend of the EPrints repository, the retrieved data of all modules appears at a previously defined location or moment, for example, right before the upload of an article.
The EPrints plug-in and further information can be found here: https://github.com/ub-regensburg/OA-EZB
7. Who can I contact if I have comments or an error?
There is a mailing list aimed at all EZB data users who regularly access data via the various interfaces of the EZB. Here you can get service-specific information from the EZB team. You can also use that mailing list to discuss with other EZB data recipients users about questions relating to the application, to contribute your own ideas and new approaches.
Link to registration: https://www.listserv.dfn.de/sympa/info/ur-ub-ezb-dbis-data
In case you found an error, please send an email to: info.ezb@ur.de