Schnittstellen und Linked Data

API

Für den automatisierten Zugriff auf das Personenregister steht eine API zur Verfügung, deren Funktionalität der einfachen und erweiterten Suche entspricht. Unter jedem Suchergebnis sowie unter jedem Personendatensatz werden im Frontend Links auf diese API mit verschiedenen Formaten ausgegeben:

  • JSON und XML: Die gefundenen Datensätze werden im JSON- bzw. XML-Format zurückgegeben und enthalten Angaben zu Person, Ämtern, GS-Nummern sowie Fundstellen.
  • JSON-LD, XML/RDF und Turtle: Eine Auswahl der Felder wird entsprechend dem Resource Description Framework (Linked Data / Semantic Web) ausgegeben (siehe unten).

Die Funktionsweise der API kann leicht aus den Suchergebnissen erschlossen werden. Die gewünschten Suchbedingungen werden über die Parameter der URL angegeben. Der format-Parameter der URL bestimmt dabei, in welcher Form die Ergebnisse ausgegeben werden.

Beispiele

a) Ein Beispiel für eine Abfrage entsprechend der einfachen Suche:

"http://personendatenbank.germania-sacra.de/api/v1.0/person?name=barbara&format=json"

Zurückgegeben werden die ersten 30 Datensätze für Personen mit dem Namen „Barbara“.

b) Ein Beispiel für eine komplexe Abfrage entsprechend der erweiterten Suche:

"http://personendatenbank.germania-sacra.de/api/v1.0/person?query[0][field]=person.vorname&query[0][value]=b*&query[0][operator]=like&query[0][connector]=or&query[1][field]=person.familienname&query[1][value]=b*&query[1][operator]=like&offset=50&limit=10&format=json-ld" 

Zurückgegeben werden Datensätze für Personen, deren Vorname oder Nachname mit „B“ beginnt. Aus den alphabetisch nach Nachnamen sortierten Ergebnissen werden die Datensätze 50 bis 59 zurückgegeben. Das Ausgabeformat ist JSON-LD.

Suchkriterien

Entsprechend der einfachen Suche sind folgende kombinierte Felder durchsuchbar:

name (durchsucht person.vorname, person.vornamenvarianten, person.namenspraefix, person.familienname, person.familiennamenvarianten, person.namenszusatz); ort (amt.institution, amt.ort, amt.dioezese); amt (amt.bezeichnung); jahr (zeitraum_von / zeitraum_bis); nummer (gsn.nummer, person.gndnummer, person.klosterid, person.cerlid, person.viaf)

Darüber hinaus können die folgenden Felder analog zur erweiterten Suche durchsucht werden: person.vorname, person.vornamenvarianten, person.namenspraefix, person.familienname, person.familiennamenvarianten, person.namenszusatz, person.herkunftsname, person.titel, person.orden, person.geburtsdatum, person.sterbedatum, person.belegdaten, person.taetigkeit, person.gndnummer, person.verwandtschaften, person.anmerkungen, amt.bezeichnung, amt.art, amt.institution, amt.ort, amt.dioezese, amt.gebiet, amt.klosterid, amt.weihegrad, amt.von, amt.bis, amt.anmerkung, gsn.nummer, fundstelle.bandnummer.

Im Suchwert wird nicht zwischen Groß- und Kleinschreibung unterschieden. Als Platzhalter kann * für eine beliebige Anzahl von Zeichen eingesetzt werden. Zusätzlich kann der Vergleichsoperator über den Parameter query[n][operator] angegeben werden, zur Verfügung stehen die Operatoren like, notlike, lower und greater. Standard ist der Operator like.

Kombination von Suchkriterien

Bis zu sechs Suchkriterien können kombiniert werden, indem Feldname, Wert und bei Bedarf ein Vergleichsoperator im query-Parameter nacheinander mit unterschiedlichen Indizes angegeben werden (query[0]…, query[1]…, query[2]… usw.).

Die Kriterien werden standardmäßig durch logische Konjunktion verknüpft, so dass die Datensätze allen angegebenen Kriterien entsprechen müssen. Die Verknüpfung zum folgenden Kriterium kann über den Parameter query[n][connector] auch explizit angegeben werden. Möglich sind die Werte and und or, wobei die Oder-Verknüpfung stärker bindet als die Und-Verknüfung. Beachten Sie bitte, dass die Reihenfolge der Kriterien durch die Reihenfolge in der URL und nicht durch die Höhe der Indizes bestimmt wird.

Begrenzung der Suchergebnisse

Standardmäßig werden die ersten 30 gefundenen Datensätze zurückgegeben, alphabetisch sortiert nach Vorname und Nachname. Alternativ kann die Anzahl der Datensätze durch den Parameter limit angegeben werden, es werden maximal 500 Datensätze je Anfrage ausgegeben.

Falls angegeben, bestimmt der Parameter offset die Position des ersten zurückgegebenen Datensatzes, wobei die Zählung bei 0 beginnt. Alternativ kann analog zur Suche in der Weboberfläche der Parameter page verwendet werden.

Auf diese Weise können nacheinander auch mehr als 500 Datensätze abgerufen werden. Entspricht kein Datensatz den Kriterien oder übersteigt der angeforderte Offset die Anzahl der Suchergebnisse oder tritt ein Fehler auf, dann wird eine leere Ergebnismenge zurückgegeben.

Linked Data

Bei der Ausgabe als Linked Data werden nur ausgefüllte Felder berücksichtigt. Die Ausgabe umfasst folgende Felder: 

  • Vorname, Familienname, Geburtsdatum und Sterbedatum
  • Amtsbezeichnung, Amtsbeginn, Amtsende, Institution und KlosterID
  • GSN und GND-Nummer

Als Vokabulare werden eingesetzt: 

Darüber hinaus werden folgende URIs zur Identifizierung von Datensätzen verwendet, wobei jeweils die GND, GSN oder KlosterID angehängt wird:

  • gnd (www.dnb.de/gnd/)
  • person (http://personendatenbank.germania-sacra.de/index/gsn/)
  • kloster (http://klosterdatenbank.germania-sacra.de/gsn/)

Die Ausgabe wird intern zunächst als JSON-LD erzeugt und dann in die Formate XML/RDF und Turtle konvertiert.

Kontakt Digitale Projekte

Akademie der Wissenschaften
zu Göttingen
Germania Sacra
Bärbel Kröger, M.A.
Geiststraße 10
D-37073 Göttingen

Telefon: +49 (0)551/39-21558
E-Mail: bkroege@gwdg.de
www: www.germania-sacra.de