Schnittstellen und Linked Data
For automated access to the registry of persons, an API is available, the functionality of which corresponds to the simple and advanced search. Under every search result as well as every dataset of a person, the frontend links to this API in varying formats:
- JSON and XML: the found datasets are retrieved in the JSON or XML-Format and contain particulars about the person, offices, GS-numbers and references.
- JSON-LD, XML/RDF and Turtle: A selection of fields is retrieved according to the Resource Description Framework (Linked Data / Semantic Web) (see below).
a) An example for a query using the simple search function: "http://personendatenbank.<wbr />germania-sacra.de/api/v1.0/<wbr />person?name=barbara&format=<wbr />json"
Retrieved are the first 30 datasets for persons with the name "Barbara".
b) An example for a complex query using the advanced search function: "http://personendatenbank.<wbr />germania-sacra.de/api/v1.0/<wbr />person?query[field]=person.<wbr />vorname&query[value]=b*&<wbr />query[operator]=like&query[<wbr />0][connector]=or&query[<wbr />field]=person.familienname&<wbr />query[value]=b*&query[<wbr />operator]=like&offset=50&<wbr />limit=10&format=json-ld"
Retrieved are datasets for persons whose first or last name begin with "B". Out of the results sorted alphabetically by last name the datasets 50 through 59 are retrieved. The result format is JSON-LD.
According to the simple search, the following combined fields can be searched: name (searches person.firstname, person.firstnamevariants, person.nameprefix, person.familyname, person.familynamevariants, person.nameadditions); place (office.institution, office.place, office.diocese); office (office.title); year (timespan_from / timespan_to); number (gsn.number, person.gndnumber, person.monasteryid, person.cerlid, person.viaf).
Furthermore, the following fields can be searched analogously to the advanced search function: person.firstname, person.firstnamevariants, person.nameprefix, person.familyname, person.familynamevariants, person.nameadditions, person.nameoforigin, person.title, person.order, person.dateofbirth, person.dateofdeath, person.documenteddates, person.occupation, person.gndnumber, person.relations, person.comments, office.title, office.type, office.institution, office.place, office.diocese, office.area, office.monasteryid, office.levelofconsecration, office.from, office.to, office.comment, gsn.number, reference.volumenumber. The search terms are not case sensitive. As a placeholder, * stands for any desired number of characters, while ? stands for one unknown character. Additionall,y the comparison operator can be given via the parameter query[n][operator]. the operators like, notlike, lower and greater are available. The standard operator is like.
Combination of Search Criteria
Up to six search criteria can be combined by adding field name, value and if necessary a
comparison operator in the query parameters with differing indices (query…, query…,
The criteria are connected by logical conjunctions, as is standard, so the datasets must
correspond to all iterated criteria. The connection to the following criterion can also be
explicitly states using the parameter query[n][connector]. The values “and” and “or” are
possible, whereby the “or”-connection binds more strongly than the “and”-connection”.
Please be aware that the order of criteria is decided by the order in the URL and not the
amount of indices.
Limitation of Search Results
Standard setting is to reveal the first thirty found datasets, alphabetically sorted by first and last
name. Alternatively, the number of datasets can be named with the parameter limits, though
there is a maximum of 500 datasets which can be revealed. If used, the parameter offset
decides the position of the first revealed dataset, whereby the count begins at 0. Alternatively, analogously to searching on the web surface, the parameter page can be used.
In this way, more than 500 successive datasets can be called up. If no dataset fits the search criteria or if the demanded offset exceeds the number, or if an error occurs, an empty result is returned.
When returning linked data, only filled fields are used. The output includes the following fields:
- First name, last name, date of birth and date of death
- Title of office, beginning of office, end of office, institution and monastery ID
- GSN and GND-number
The following vocabularies are used:
- foaf (xmlns.com/foaf/0.1/) for the labeling of object types (organisation, person) and for the assignation of organisation names and office types.
- rdf (http://www.w3.org/1999/02/22-<wbr/>rdf-syntax-ns#) for the assignation of the type of object (organisation, person)
- par (purl.org/vocab/<wbr/>participation/schema) for the assignation of offices to persons and institutions
- owl (http://www.w3.org/2002/07/<wbr/>owl#) for the labeling of numbers / IDs
- schema (schema.org) for the labeling of person names and birth and death dates
- org (http://www.w3.org/ns/org#) for the labeling of membership in the institutions
- rdfs (http://www.w3.org/2000/01/<wbr/>rdf-schema#) for the collection of multiple datasets of persons in one container.
Furthermore, the following URIs are used for the identification of datasets, whereby the GND, GSN or monastery ID respectively are attached:
- gnd (http://d-nb.info/gnd/)
- person (http://personendatenbank.<wbr/>germania-sacra.de/index/gsn/)
- kloster (http://klosterdatenbank.<wbr/>germania-sacra.de/gsn/)
The retrieved data is first generated as JSON-LD internally and then converted to the formats XML/RDF and Turtle.