JSON-API der Deutschen ISIL-Agentur und Sigelstelle (beta)
Zur automatisieten Abfrage der ISIL- und Adressdaten stellt die Deutsche ISIL-Agentur und Sigelstelle eine webbasierte Programmierschnittstelle (API) bereit, die die Daten in der JavaScript Notation JSON zurückgibt.
Einfache Suchanfrage
Eine einfache Suche kann in der Form
/api/org.jsonld?q={Suchterme}
formuliert werden.
Die Suchterme können in gleicher Weise, wie in Hilfe zur Suche beschrieben, gebildet bzw. kombiniert werden. Dabei müssen die Suchterme als Wert für den Parameter q URL-codiert sein.
Beispielanfrage (mit nam=Institut AND ort=München)
https://sigel.staatsbibliothek-berlin.de/api/org.jsonld?q=nam%3Dinstitut%20AND%20ort%3Dm%C3%BCnchen
Parameter, die die Antwort beeinflussen
Das Ergebnis einer Anfrage kann über zwei URL-Parameter beeinflusst werden
- size - Die Anzahl der Ergebnisse pro Seite. Der Default Wert ist 10
- page - Die Nummer der Ergebnisseite, die angezeigt werden soll. Der Default Wert ist 1
- compact - Der PICA-Datensatz in kompakter Form (ein Array pro Kategorie). Muss einen anderen Wert als 0 enthalten
Beispielanfrage (mit size=5 und page=2)
Beispielanfrage (mit compact=1)
Antwort in JSON
Die Antwort auf eine Suchanfrage wird in Form eines JSON-Objekts gegeben, welches im Grunde aus drei Teilen besteht:
- Metadaten der Suchanfrage
- ISIL-/Adressdaten
- Links zur Navigation und Information zur aktuellen Ergebnisseite
Metadaten der Suchanfrage
Die Metadaten zur Suchanfrage bestehen aus folgenden Schlüsseln:
- id - URL der ursprünglich gestellten Suchanfrage
- freetextQuery - die Suchterme
- totalItems - Absolute Anzahl der Ergebnisse
- type - Der Typ einer Ergebnismenge ist immer Collection
ISIL- und Adressdaten
Die eigentlichen ISIL- und Adressdaten werden unter dem Schlüssel member in einem JSON-Array zusammengefasst. Jeder ISIL- und Adressdatensatz hat folgende Schlüssel:
- id - URL, der den Datensatz identifiziert
- type - Liste der Einrichtungstypen
- seeAlso - URL einer RDF-Repräsentation der Daten
- sameAs - wie seeAlso
- identifier - das ISIL
- location - Ort der Einrichtung
- addressRegion - Abkürzung der Fernleihregion
- data - der PICA-Plus-Datensatz in Form eines JSON-Objekts
Gibt es keine Ergebnisse für die Anfrage, dann wird ein leeres JSON-Array zurückgegeben.
ISIL- und Adressdaten (kompakte Ansicht)
Wenn der Parameter compact genutzt wird, dann wird jeder Datensatz mit den Schlüsseln
- _id - Datensatznummer (ISIL)
- record - der PICA-Plus-Datensatz in Form eines JSON-Arrays
ausgegeben.
Gibt es keine Ergebnisse für die Anfrage, dann wird ein leeres JSON-Array zurückgegeben.
Links zur Navigation in der Ergebnismenge
Da die Ergebnisse möglicherweise auf mehrere Antwortseiten aufgeteilt sind, werden Links zur Navigation in diesen Seiten benötigt. Diese Navigation ist unter dem Schlüssel view als JSON-Objekt zusammengefasst und enthält die Schlüssel:
- id - Link zur aktuellen Seite
- type - ist immer PartialCollectionView
- first - Link zur ersten Seite
- last - Link zur letzten Seite
- totalItems - Anzahl der Datensätze, die auf der aktuellen Seite angezeigt werden
- pageIndex - Nummer der aktuellen Seite
- numberOfPages - Anzahl der Ergebnisseiten
- offset - Nummer des ersten Datensatzes auf der aktuellen Seite
- limit - Maximale Anzahl von Ergebnissen auf einer Seite
und möglicherweise
- previous - Link zur vorherigen Seite, falls vorhanden
- next - Link zur nächsten Seite, falls vorhanden
JSONP
Optional können die Ergebnisse in einem Funktionsaufruf umschlossen werden (JSONP). So können die Daten direkt an eine Callback-Funktion des Clients übergeben werden. JSONP wird durch den Paramater callback erzeugt. Der Wert des Parameters ist der Name der Funktion des Clients (Callback-Funktion), mit dem die Daten weiterverarbeitet werden sollen.
Eine entsprechende Anfrage hätte dann die Form:
/api/org.jsonld?q={Suchterme}&callback={Name_der_Callback-Funktion}
Ein weiterer Parameter format beeinflusst den Umfang der Daten, die als JSONP ausgegeben werden. Hat der Parameter den Wert lookup, dann werden nur die häufigsten Daten ausgeben. Mit dem Wert data werden nur JSON-kodierte PICA+-Daten in die Callback-Funktion eingeschlossen. Entsprechend lautet die Syntax:
/api/org.jsonld?q={Suchterme}&callback={Name_der_Callback-Funktion}&format={lookup|data}
Beispielanfrage (Name der Callback-Funktion = list, Format = lookup)
https://sigel.staatsbibliothek-berlin.de/api/org.jsonld?q=ort%3DBonn&callback=list&format=lookup
Abfrage einzelner Datensätze
Jeder Datensatz kann einzeln mit Hilfe eines ISIL abgerufen werden:
/api/org/{ISIL}.jsonld
Beispielanfrage (mit ISIL DE-12)
https://sigel.staatsbibliothek-berlin.de/api/org/DE-12.jsonld
Daten der Zeitschriftendatenbank (ZDB)
Siehe hierzu https://www.zeitschriftendatenbank.de/services/schnittstellen/json-api/
Kontakt
Bei Fragen zur JSON-API und bei Anmerkungen zur Verbesserung wenden Sie sich bitte an:
|
Carsten Klee |
|---|
|
Tel.: +49 30 266 434402 |
sbb.spk-berlin.de