JSON-API (beta)

Zur automatisierten Abfrage der ZDB-Titeldaten stellt die Zeitschriftendatenbank eine webbasierte Programmierschnittstelle (API) bereit, die die Daten in der JavaScript Notation JSON zurückgibt.

Einfache Suchanfrage

Eine einfache Suche kann in der Form

https://zeitschriftendatenbank.de/api/tit.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 iss=1031-2153)

https://zeitschriftendatenbank.de/api/tit.jsonld?q=iss%3D1031-2153

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 - Erzeugt eine flache, kompakte Array-Darstellung direkt unter dem member-Schlüssel

Beispielanfrage (mit size=5 und page=2)

https://zeitschriftendatenbank.de/api/tit.jsonld?q=Zeitung&size=5&page=2

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
• ZDB-Titeldaten
• 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

ZDB-Titeldaten

Die eigentlichen Titeldaten werden unter dem Schlüssel member in einem JSON-Array zusammengefasst. Jeder Titeldatensatz hat folgende Schlüssel:

• id - URL, der den Datensatz identifiziert
• type - Liste der Publikationstypen
• seeAlso - URL einer RDF-Repräsentation der Daten
• sameAs - wie seeAlso
• identifier - die ZDB-ID
• medium- Medientyp (print, audiovisual, braille, microform, online, electronic)
• issn - Liste der gültigen ISSNs
• title - Titel der Publikation
• temporal - Erscheinungsverlauf
• publisher- Publikationsvermerk
• 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.

Links zur Navigation und Information zur aktuellen Ergebnisseite

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:

https://zeitschriftendatenbank.de/api/tit.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:

https://zeitschriftendatenbank.de/api/tit.jsonld?q={Suchterme}&callback={Name_der_Callback-Funktion}&format={lookup|data}

Beispielanfrage (Name der Callback-Funktion = list, Format = lookup)

https://zeitschriftendatenbank.de/api/tit.jsonld?q=iss%3D1031-2153&callback=list&format=lookup

Abfrage einzelner Datensätze

Jeder Datensatz kann einzeln mit Hilfe einer ZDB-ID abgerufen werden:

https://zeitschriftendatenbank.de/api/tit/{ZDB-ID}.jsonld

Beispielanfrage (mit ZDB 873319-3)

https://zeitschriftendatenbank.de/api/tit/873319-3.jsonld

ISIL-Daten der Deutschen ISIL-Agentur und Sigelstelle

Siehe hierzu http://sigel.staatsbibliothek-berlin.de/suche/json-api/

Kontakt

Bei Fragen zur JSON-API und bei Anmerkungen zur Verbesserung wenden Sie sich bitte an: