DBIS JSON Rest API

Link to the interface and interface description (interactive Swagger documentation): https://dbis-api.ur.de

1. What is the DBIS JSON Rest API?

All endpoints that return their data as JSON were recreated during the code upgrade and are the recommended way to query DBIS data for the new DBIS version (release 10/2024), especially for data-intensive queries.

Please note: Bibliographic and other descriptive data on academic databases, collected and maintained jointly by all DBIS institutions, are made available under the Creative Commons Zero (CC0 1.0) license. However, before locally valid data can be retrieved in the JSON Rest API, the respective DBIS user institution must agree to the data exchange permission of its own institution’s locally valid data under the Creative Commons Zero (CC0 1.0) license in the admin interface. A list of institutions that have agreed to the data exchange permission is available in the API.

The API is intended for technical use and the endpoints can be connected via script. A tool is also available in the DBIS interface for easily extracting data via CSV download.

2. Input Parameters

The following parameters can be passed to the interface:

Input Parameters	Value	Default Value	Description
language	‘de’ or ‘en’	de’	Selection of the language for the output data. You can choose between “de” or “en”
url_bibid		/	The unique identifier of a participating organization, also known as the URL-BIBID. It is displayed in the admin area. The output data represents the local view of this organization and not the global data.
resource_count	false/true	false	Indicates the number of resources associated with a specific subject area (yes/no)
include_unlicensed	false/true	false	Also includes unlicensed resources (red traffic light) (yes/no)
subject_id		/	The internal ID of the subject area (can be retrieved via the subjects endpoint)
collection_id		/	The internal ID of a collection (can be retrieved via the endpoint collections/organization/{url_bibid})
dbis_res_id		/	ID of the desired resource. Use other endpoints (such as “resourceIdsBySubject” or “resourceIdsGlobal”) to retrieve lists of these IDs
	null	/	empty field

3. Status Messages

The following table provides an overview of the possible status messages that can be output by the interface.

Status-Code	Status Message (DE)	Status Message (EN)
200	Gibt die angeforderten Daten zurück.	Returns requested data
403	Wird zurückgegeben, wenn die angeforderten Daten auf „unsichtbar“ gesetzt sind.	Returned when the requested data is set to invisible
404	Wird zurückgegeben, wenn entweder die Ressource oder die Institution nicht gefunden wurde.	Is returned when either the resource or the institution was not found.

4. Important Output Fields

Exactly which data is returned and the context in which it should be understood depends on the specific endpoint being used.

Output Fields	Description
is_free	This input field refers to the database’s pricing type. There are two options: “This database is freely available on the Internet” (= true) “This database requires a license” (= false)
traffic_light	The traffic light color depends on the database license: Green = freely available Yellow = licensed to my organization Red = not available to my organization
types	This output field displays the database type or types. The following options are available: Address and business directory General reference resource Article database Inventory list Biographical database Book trade directory Disciplinary research data repositories Disciplinary repositories Subject bibliography Factual database National and regional bibliography Portal Collection of non-textual materials Full-text database Dictionary, encyclopedia, reference work Newspaper Newspaper and journal bibliography
type	This input field refers to license types. The following license types are available in DBIS: Freely available Local license National license FID license Consortium license Remote access
type	This input field refers to access types. The following access types are available in DBIS: Organizational Network / VPN On-site Access Shibboleth EZProxy HAN Link with Registration Single-User
form	This output field refers to the form types. The following form types exist in DBIS: Online Application software Data carriers
countries	Countries, continents, federal states, or historical geographical names to which the database content refers. The following countries are available for selection in DBIS: Africa Albania Ancient Near East America Andorra Asia Australia, Oceania Baden-Württemberg Baltic States Bavaria Belgium Berlin Bosnia and Herzegovina Brandenburg Bremen Bulgaria Byzantine Empire Denmark Germany Germany (GDR) Estonia Europe Finland France Gibraltar Greece Greece (Ancient) Great Britain CIS Hamburg Hesse Ireland Iceland Italy Israel Yugoslavia Canada Croatia Latvia Liechtenstein Lithuania Luxembourg Macedonia Malta Mecklenburg-Western Pomerania Central America Moldova Monaco Montenegro Netherlands Lower Saxony North America North Rhine-Westphalia Norway Austria Ottoman Empire Eastern Europe Eastern Central Europe Palestine Poland Portugal Rhineland-Palatinate Roman Empire Romania Russia, Soviet Union Saarland Saxony Saxony-Anhalt San Marino Schleswig-Holstein Sweden Switzerland Serbia Scandinavia Slovakia Slovenia Spain South America Southeast Europe Thuringia Czech Republic Turkey Ukraine Hungary USA Vatican City Belarus Cyprus Unknown Southeast Asia South Asia East Asia Japan China Korea
external_ids	This output field displays the external identifiers. The following options are available: ZDB: ZDB ID / ZDB product seal / ISIL Fidelio: PICA Production Number (PPN) EZB: Package ID / Collection ID re3data: DOI RefHunter: link

5. DBIS API Endpoints

You can use the parameters provided to retrieve and display the data you need.

The following endpoints are part of the DBIS API:

5.1 /api/v1/subjects

List of all globally defined subjects.

Output Fields	Description
id	subject ID
title	subject title
subject_system	subjects, analogous to EZB subject, based on RVK main groups
parent	null
is_collection	is a collection (true / false)

5.2 /api/v1/subjects/organization/{url_bibid}

List of an organization’s defined subjects.

An organization can hide a globally defined subject locally. This subject will then not appear in this list.

An organization can define its own local collections. A collection can be marked so that it is treated as a subject. If this is the case, the collection will also appear as a subject in the results of this endpoint (is_collection = true).

For each subject, the number of databases contained for that organization is displayed.

Output Fields	Description
id	subject ID
title	subject title
is_collection	is a collection (true / false)
resource_count	number of associated databases

5.3 /api/v1/collections/organization/{url_bibid}

A list of the ID, title, and number of databases contained in all locally defined collections of an organization. The “is_subject” output field indicates whether a collection is also a subject or was created as a collection that does not appear in the list of subjects.

Output Fields	Description
id	collection ID
title	collection title
is_subject	collection is subject (true / false)
resource_count	number of associated databases

5.4 /api/v1/resourceIdsBySubject/{subject_id}

A list of the IDs of all databases contained in DBIS (the entire DBIS collection) that are displayed to the user (i.e., not globally hidden) and that belong to a specific subject.

Output Fields	Description
ids	resource IDs of all databases of a subject

5.5 /api/v1/resourceIdsBySubject/{subject_id} /organization/{url_bibid}

A list of the IDs of all databases from an organization that are displayed to the user and that the organization has assigned to a specific subject.

Output Fields	Description
ids	resource IDs of the databases belonging to a subject within a specific organization

5.6 /api/v1/topResourceIdsBySubject/{subject_id} /organization/{url_bibid}

A list of the IDs of all top databases in a specific subject, as defined by a specific organization.

Output Field	Description
ids	resource IDs of all top databases in a subject area within a specific organization

5.7 /api/v1/resourceIdsByCollection/{collection_id} /organization/{url_bibid}

A list of the IDs of all databases belonging to an organization that are part of a specific collection.

Output Fields	Description
ids	resource IDs of the databases belonging to an organization’s collection

5.8 /api/v1/topResourceIdsByCollection/{collection_id} /organization/{url_bibid}

A list of the IDs of all top databases in a specific collection, as defined by a specific organization.

Output Fields	Description
ids	resource IDs of all top databases in a collection belonging to a specific organization

5.9 /api/v1/resourceIds

A list of the IDs of all databases in the DBIS collection that are displayed to the user (i.e., those that are not globally hidden).

Output Fields	Description
ids	resource IDs of all global databases in the DBIS master collection

5.10 /api/v1/resourceIds/organization/{url_bibid}

A list of all databases displayed to users from a specific organization.

Output Fields	Description
ids	resource IDs for all databases in a specific organization

5.11 /api/v1/resource/{dbis_res_id}

A list of all details for a specific database. The traffic light colors correspond to those displayed in the “Total Inventory” view.

Please note: License and access information is only displayed if the database is freely available (i.e., is_free = true). For databases that require a license (is_free = false), this information is not displayed.

Output Fields	Description
traffic_light	traffic light color (green / yellow / red)
id	resource ID of the database
title	database title
is_free	freely available (true / false)
description_short	short description (displayed in the DBIS results list)
description	description (displayed on the DBIS details page)
report_time_start	beginning of the reporting period
report_time_end	end of the reporting period
publication_time_start	start of the publication period
publication_time_end	end of the publication period
is_still_updated	1 = unknown 2 = no longer updated 3 = still being updated
update_frequency	update frequency
note	notes
isbn_issn	ISBN/ISSN number
local_note	local notes
instructions	instructions
created_at	date of creation
modified_at	date of last update
authors	publisher
types	database type
title	database type title
description	database type description
id	database type ID
licenses	licenses
id	license ID
resourceId	null
form	license form
id	license form ID
title	license form title
description	license form description
type	license type
id	license type ID
title	license type title
description	license type description
isGlobal	is global (true / false)
licenseLocalisation	license localization
textMiningAllowed	text mining allowed (true / false)
fid	FID license
isAllowingWalking	walkin user allowed (true / false)
numberOfConcurrentUsers	number of concurrent users
validFromDate	valid from date
validToDate	valid to date
externalNotes	external notes
vendor	vendor
publisher	publisher
id	publisher ID
title	publisher title
accesses	accesses
id	access ID
type	access type
id	access type ID
title	access type title
description	access type description
isGlobal	is global
form	access form
license	access license
accessUrl	access URL
manualUrl	link to manual
_404Url	null
label	access label
labelLong	access label usage
labelLongest	access label usage (long description)
description	access label description
requirements	requirements
host	host
organization	null
state	up
resource	null
shelfmark	shelfmark
isMainAccess	main link to the link ‘To the database’ (true / false)
access_hash	null
label_id	access label ID
publicationForm	formal type
title	formal type title
description	formal type description
id	formal type ID
external_ids	external identifiers for license and access information
created_at	date of creation
modified_at	date of last update
subjects	subjects
id	subject ID
title	subject title
subject_system	Subject, analogous to EZB subject, based on RVK main groups
parent	null
is_collection	is collection (true / false)
collections	collections
keywords	keywords
id	keyword ID
title	keyword title
external_id	keyword GND ID
keyword_system	GND
top_resource_entries	top database entries
alternative_titles	alternative title
id	alternative title ID
title	title of alternative title
valid_to	alternative title valid to
valid_from	alternative title valid from
countries	countries
title	country title
code	country code
id	country ID
external_ids	external identifier
namespace	ZDB / FIDELIO / EZB / re3data / RefHunter
id	ZDB / ISIL / EZB ID / re3data DOI / RefHunter link
id_name	ZDB-ID / ZDB-Produktsigel / ISIL / PICA production number (PPN) / package ID / collection ID re3data RefHunter
api_urls	Link to the database’s API or API documentation, if an interface is provided

5.12 /api/v1/resource/{dbis_res_id}/organization/{url_bibid}

A list of all details for a specific resource from the perspective of a specific organization.

Output Fields	Description
traffic_light	traffic light color (green / yellow / red)
id	resource ID of database
title	database title
is_free	freely available (true / false)
description_short	short description (displayed in DBIS results list)
description	description (displayed on DBIS detail page)
report_time_start	start of reporting period
report_time_end	end of reporting period
publication_time_start	start of publication period
publication_time_end	end of publication period
is_still_updated	1 = unknown 2 = no longer updated 3 = still being updated
update_frequency	update frequency
note	notes
isbn_issn	ISBN/ISSN number
instructions	instructions
created_at	date of creation
modified_at	date of last update
authors	authors
types	database type
title	database type title
description	database type description
id	database type ID
licenses	licenses
id	license ID
resourceId	null
form	license form
id	license form ID
title	license form title
description	license form description
type	license type
id	license type ID
title	license type title
description	license type description
isGlobal	is global (true / false)
licenseLocalisation	license localization
id	ID
license	license ID
organisation	URL-BIBID
externalNotes	external notes
inputDate	input date
isActive	active license (true / false)
textMiningAllowed	text mining allowed (true / false)
fid	FID license
isAllowingWalking	walkin user allowed (true / false)
numberOfConcurrentUsers	number of concurrent users
validFromDate	valid from date
validToDate	valid to date
externalNotes	external notes
vendor	vendor
publisher	publisher
id	publisher ID
title	publisher title
accesses	access
id	access ID
type	access tpe
id	access type ID
title	access type title
description	access type description
isGlobal	is global (true / false)
form	access form
Id	access form ID
title	access form title
license	access form license
accessUrl	access URL
manualUrl	link to manual
_404Url	null
label	access label
labelLong	access label usage
labelLongest	access label usage (long description)
description	access label description
requirements	requirements
host	host
organization	null
state	up
resource	null
shelfmark	shelfmark
isMainAccess	main link to the link ‘To the database’ (true / false)
access_hash	null
label_id	access label ID
publicationForm	formal type
title	formal type title
description	formal type description
id	formal type ID
external_ids	external identifiers for license and access information
created_at	date of creation
modified_at	date of last update
subjects	subjects
id	subject ID
title	subject title
subject_system	subject, analogous to EZB subject, based on RVK main groups
parent	null
is_collection	is collection (true / false)
collections	collections
keywords	keywords
id	keyword ID
title	keyword title
external_id	keyword GND ID
keyword_system	GND
top_resource_entries	top database entries
alternative_titles	alternative title
id	alternative title ID
title	title of alternative title
valid_to	alternative title valid to
valid_from	alternative title valid from
countries	countries
title	country title
code	country code
id	country ID
external_ids	external identifier
namespace	ZDB / FIDELIO / EZB / re3data / RefHunter
id	ZDB / ISIL / EZB ID / re3data DOI / RefHunter link
id_name	ZDB-ID / ZDB-Produktsigel / ISIL / PICA production number (PPN) / package ID / collections ID re3data RefHunter
api_urls	Link to the database’s API or API documentation, if an interface is provided

5.13 /api/v1/resourceES/{dbis_res_id}/organization/{url_bibid}

A list of all details for a specific resource from the perspective of a specific organization.

Output Fields	Description
traffic_light	traffic light color (green / yellow / red)
resource_id	resource ID of database
resource_title	database title
alternative_titles	alternative title
id	alternative title ID
title	title of alternative title
valid_from	alternative title valid from
valid_to	alternative title valid to
description	description (displayed on DBIS detail page)
description_short	short description (displayed on DBIS results list)
report_time_start	beginning of reporting time
report_time_end	end of reporting time
publication_time_start	beginning of publication time
publication_time_end	end of publication time
note	note
isbn_issn	ISBN / ISSN number
instructions	instructions
is_free	freely available (true / false)
resource_localisations	resource localization
id	ID
note	locally overwritten data
title	locally overwritten data
resource	database ID
isbn_issn	ISBN / ISSN number
shelfmark	shelfmark
created_at	date of creation
is_visible	is visible (true / false)
desciption	description
modified_at	date of last update
instructions	instructions
organisation	URL-BIBID
title_original	original title
report_time_end	end of reporting period
is_still_updated	1 = unknown 2 = no longer updated 3 = still being updated
update_frequency	update frequency
description_short	short description
report_time_start	beginning of reporting period
publication_time_end	end of publication period
publication_time_start	beginning of publication period
update_frequency_text_from_old_dbis	null
keywords	keywords
id	keyword ID
title	keyword title
external_id	keyword GND ID
keyword_system	GND
authors	authors
subjects	subjects
id	subject ID
title	subject title
parent	null
sort_by	1
subject_system	subjects, analogous EZB subjects, based on RVK main groups
is_top_database	is top database (true / false)
sort_order	100000
collections	collections
is_top_database_in_subjects	is top database in subjects
is_top_database_in_collections	is top database in collections
countries	countries
licenses	licenses
id	license ID
resource	resource ID
type	license type
id	license type ID
title	license type title
description	license type description
isGlobal	is global (true / false)
form	license form
id	license form ID
title	license form title
description	license form description
is_allowing_data_mining	data mining allowed (true / false)
vendor	vendor
publisher	publisher
title	publisher title
id	publisher ID
last_check	last check
created_at	date of creation
modified_at	date of last update
is_global	is global (true / false)
accesses	accesses
id	access ID
form	access form
host	host
type	access type
id	access type ID
title	access type title
description	access type description
isGlobal	is global (true / false)
label	access label
state	status500
license	access license
label_id	access label ID
shelfmark	shelfmark
description	description
organization	null
requirements	requirements
isMainAccess	main link to the link ‘To the database’ (true / false)
accessUrl	access URL
manualUrl	link to manual
_404Url	null
labelLong	access label usage
labelLongest	access label usage (long description)
isActive	active license (true / false)
publicationForm	formal type
id	formal type ID
title	formal type title
description	formal type description
isAllowingWalking	walkin user allowed (true / false)
externalNotes	external notes
numberOfConcurrentUsers	number of concurrent users
external_resource_ids	–
id	external identifier ID
resource	database ID
namespace	name of identifier (ZDB / EZB / re3data / RefHunter)
created_at	date of creation of identifier
external_id	ID of ZDB / EZB / re3data / RefHunter identifier
modified_at	date of last update of identifier
external_id_name	type of external identifier (e.g., ID / Produktsigel)
created_at	date of creation
modified_at	date of last update
types	database type
id	database type ID
title	database type title
description	database type description

5.14 /api/v1/licenseTypes

A list of the details for all defined license types.

Output Fields	Description
id	license type iD
title	license type title
de	German type of license type
en	English type of license type
description	license type description
isGlobal	is global (true / false)

5.15 /api/v1/licenseForms

A list of the details for all defined license types.

Output Fields	Description
id	license form ID
title	license form title
de	German title of license form
en	English title of license form
description	license form description
de	German description of license form
en	English description of license form

5.16 /api/v1/accessTypes

List of details for all defined access types.

Output Fields	Description
id	access type ID
title	access type title
de	German title of access type
en	English title of access type
description	access type description
isGlobal	is global (true / false)

5.17 /api/v1/accessForms

A list of the details for all defined access types.

Output Fields	Description
id	access form ID
title	access form title
de	German title of access form
en	English title of access form

5.18 /api/v1/dataSharingConsent

List of all organizations that have agreed to make their locally valid DBIS data available.

Bibliographic and other descriptive data on scientific databases, which are collected and maintained jointly by all DBIS organizations, are made available under the Creative Commons Zero (CC0 1.0) license.

In contrast, the release of locally valid data from DBIS organizations—such as their own license data, collections, and TOP databases—is subject to the consent of the respective DBIS organization.

If you grant permission for the reuse of your organization’s locally applicable DBIS data, the Regensburg University Library is authorized to supply your DBIS data to third-party systems with open knowledge bases. This means that your shared DBIS data is publicly readable and searchable by anyone, and may be downloaded and reused without restriction.

Your organization may revoke this consent at a later date. However, please note that DBIS data already delivered by the Regensburg University Library to third-party systems will generally not be deleted after consent is revoked. Once consent is revoked, your DBIS data will be excluded from the interfaces and from future data deliveries to third parties.

If you do not authorize the reuse of your organization’s locally valid DBIS data, it will be excluded from the interfaces and data delivery services for sharing with third parties.

Output Field	Description
url-bib-id	URL-BIBID

6. Who can I contact if I have comments or find errors?

Please let us know at info.dbis@ur.de if you have any further requirements that are not covered by the existing endpoints, or if you notice any errors.

There is also a mailing list for all EZB and DBIS data recipients. Here you will find service-specific information on changes, innovations, and notices of disruptions or maintenance work. You will also have the opportunity to exchange questions about the application with other data consumers, contribute your own ideas, and discuss new approaches.

Link to registration: https://www.listserv.dfn.de/sympa/info/ur-ub-ezb-dbis-data