zur Staatsbibliothek
 
Search > JSON-API

 
 

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)

https://sigel.staatsbibliothek-berlin.de/api/org.jsonld?q=nam%3Dinstitut%20AND%20ort%3Dm%C3%BCnchen&size=5&page=2

Beispielanfrage (mit compact=1)

https://sigel.staatsbibliothek-berlin.de/api/org.jsonld?q=nam%3Dinstitut%20AND%20ort%3Dm%C3%BCnchen&size=1&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

carsten.kleesbb.spk-berlin.de