API verwenden

Inhalt

Einführung

Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben möchten, die mit der Books API interagieren können. Google Books hat es sich zur Aufgabe gemacht, die Buchinhalte der Welt zu digitalisieren und so im Web leichter auffindbar zu machen. Mit der Books API kannst du diese Inhalte suchen und darauf zugreifen sowie Personalisierungen für diese Inhalte erstellen und anzeigen.

Wenn Sie mit den Konzepten von Google Books nicht vertraut sind, sollten Sie den Artikel Erste Schritte lesen, bevor Sie mit dem Programmieren beginnen.

Anfragen autorisieren und Ihre Anwendung identifizieren

Alle Anfragen, die Ihre Anwendung an die Books API sendet, müssen Ihre Anwendung bei Google identifizieren. Dafür gibt es zwei Möglichkeiten: die Verwendung eines OAuth 2.0-Tokens, das auch die Anfrage autorisiert, und/oder die Verwendung des API-Schlüssels der Anwendung. Welche dieser Optionen Sie nutzen sollten, hängt von Folgendem ab:

  • Wenn die Anfrage eine Autorisierung erfordert (z. B. eine Anfrage nach privaten Daten einer Person), muss die Anwendung ein OAuth 2.0-Token mit der Anfrage bereitstellen. Die Anwendung kann auch den API-Schlüssel bereitstellen, muss dies jedoch nicht.
  • Wenn die Anfrage keine Autorisierung erfordert, beispielsweise bei einer Anfrage in Bezug auf öffentliche Daten, muss die Anwendung entweder den API-Schlüssel oder ein OAuth 2.0-Token oder beides bereitstellen, je nachdem, was für Sie am bequemsten ist.

Über Autorisierungsprotokolle

Ihre Anwendung muss zur Autorisierung von Anfragen OAuth 2.0 verwenden. Andere Autorisierungsprotokolle werden nicht unterstützt. Wenn deine Anwendung Über Google anmelden verwendet, werden einige Schritte der Autorisierung automatisch ausgeführt.

Anfragen mit OAuth 2.0 autorisieren

Anfragen an die Books API für nicht öffentliche Nutzerdaten müssen von einem authentifizierten Nutzer autorisiert werden.

Die Details dieses Autorisierungsablaufs für OAuth 2.0 hängen davon ab, welche Art von Anwendung du schreibst. Die folgende allgemeine Vorgehensweise gilt für alle Arten von Anwendungen:

  1. Wenn Sie Ihre Anwendung erstellen, registrieren Sie diese über die Google API Console. Google stellt Ihnen dann die Informationen bereit, die du später benötigst, z. B. eine Client-ID und einen Clientschlüssel.
  2. Aktivieren Sie die Books API in der Google API Console. Überspringe diesen Schritt, falls die API nicht in der API Console aufgeführt ist.
  3. Wenn deine Anwendung Zugriff auf Nutzerdaten benötigt, bittet sie Google um einen bestimmten Zugriffsbereich.
  4. Dem Nutzer wird von Google ein Zustimmungsbildschirm angezeigt, auf dem er gebeten wird, deine Anwendung dazu zu autorisieren, einige seiner Daten abzufragen.
  5. Wenn der Nutzer zustimmt, erhält deine Anwendung von Google ein kurzlebiges Zugriffstoken.
  6. Die Anwendung fordert Nutzerdaten an, wobei das Zugriffstoken an die Anfrage angehängt wird.
  7. Stellt Google fest, dass Ihre Anfrage und das Token gültig sind, werden die angeforderten Daten zurückgegeben.

Einige Abläufe enthalten zusätzliche Schritte, beispielsweise die Verwendung von Aktualisierungstoken zum Erhalt neuer Zugriffstoken. Weitere Informationen über die Abläufe für die unterschiedlichen Anwendungstypen findest du in der OAuth 2.0-Dokumentation.

Hier finden Sie die Informationen zum OAuth 2.0-Bereich für die Books API:

https://www.googleapis.com/auth/books

Zur Anforderung eines Zugriffs mit OAuth 2.0 benötigt Ihre Anwendung die Informationen zum Umfang sowie die Informationen, die Google bei der Registrierung Ihrer Anwendung bereitstellt, z. B. die Client-ID und den Clientschlüssel.

Tipp: Die Google APIs-Clientbibliotheken können einige Schritte des Autorisierungsvorgangs für Sie übernehmen. Diese sind in zahlreichen Programmiersprachen verfügbar. Weitere Informationen dazu finden Sie auf der Seite mit Bibliotheken und Beispielen.

API-Schlüssel erhalten und nutzen

Anfragen an die Books API für öffentliche Daten muss eine Kennung erfolgen. Diese kann ein API-Schlüssel oder ein Zugriffstoken sein.

So erhalten Sie einen API-Schlüssel:

  1. Öffnen Sie in der API Console die Seite „Anmeldedaten“.
  2. Diese API unterstützt zwei Arten von Anmeldedaten. Erstellen Sie die Anmeldedaten, die für Ihr Projekt geeignet sind:
    • OAuth 2.0: Wenn Ihre Anwendung private Nutzerdaten anfordert, muss sie zusammen mit der Anfrage ein OAuth 2.0-Token senden. Die Anwendung sendet zuerst eine Client-ID und möglicherweise einen Clientschlüssel, um ein Token zu erhalten. Sie können OAuth 2.0-Anmeldedaten für Webanwendungen, Dienstkonten oder installierte Anwendungen generieren.

      Weitere Informationen finden Sie in der OAuth 2.0-Dokumentation.

    • API-Schlüssel: Eine Anfrage, die kein OAuth 2.0-Token bereitstellt, muss einen API-Schlüssel senden. Mit diesem Schlüssel werden Ihr Projekt identifiziert sowie der API-Zugriff, das Kontingent und Berichte bereitgestellt.

      Die API unterstützt mehrere Arten von Einschränkungen für API-Schlüssel. Wenn der erforderliche API-Schlüssel noch nicht vorhanden ist, erstellen Sie einen API-Schlüssel in der Console, indem Sie auf Anmeldedaten erstellen > API-Schlüssel klicken. Sie können den Schlüssel einschränken, bevor Sie ihn in der Produktionsumgebung verwenden. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie eine der Einschränkungen aus.

Folgen Sie zur Wahrung der Sicherheit Ihrer API-Schlüssel den Best Practices zur sicheren Verwendung von API-Schlüsseln.

Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen.

Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.

Google Books-IDs

Sie müssen ID-Felder für bestimmte API-Methodenaufrufe angeben. In Google Books werden drei Arten von IDs verwendet:

  • Volume-IDs: eindeutige Strings für jedes Band, das Google Books bekannt ist. Ein Beispiel für eine Volume-ID ist _LettPDhwR0C. Sie können die API verwenden, um die Volume-ID abzurufen. Stellen Sie dazu eine Anfrage, bei der eine Volume-Ressource zurückgegeben wird. Sie finden die Volume-ID im Feld id.
  • Bücherregal-IDs: Numerische Werte, die einem Bücherregal in der Bibliothek eines Nutzers zugewiesen werden. Google bietet für jeden Nutzer vordefinierte Regale mit den folgenden IDs:
    • Favoriten: 0
    • Gekauft: 1
    • Lesevorgang: 2
    • Aktuell gelesen: 3
    • Gelesen: 4
    • Überprüft: 5
    • Zuletzt aufgerufen: 6
    • Meine E-Books: 7
    • Bücher für dich: 8 Wenn wir keine Empfehlungen für den Nutzer haben, ist dieser Bereich nicht vorhanden.
    Benutzerdefinierte Regale haben IDs mit mehr als 1.000. Eine Bücherregal-ID ist für einen bestimmten Nutzer eindeutig. Das bedeutet, dass zwei Nutzer ein Bücherregal mit derselben ID haben können, das sich auf verschiedene Bücherregale bezieht. Sie können die API verwenden, um die Bücherregal-ID abzurufen. Stellen Sie dazu eine Anfrage, die eine Bücherregal-Ressource zurückgibt. Sie finden die Bücherregal-ID im Feld id.
  • Nutzer-IDs: Eindeutige numerische Werte, die jedem Nutzer zugewiesen sind. Diese Werte müssen nicht unbedingt mit dem ID-Wert übereinstimmen, der in anderen Google-Diensten verwendet wird. Derzeit kann die User-ID nur durch Extrahieren aus dem SelfLink in einer mit einer authentifizierten Anfrage abgerufenen Bücherregalressource abgerufen werden. Nutzer können ihre eigene Nutzer-ID auch über die Google Books-Website erhalten. Ein Nutzer kann die Nutzer-ID nicht über die API oder die Google Play Bücher-Website abrufen. Der andere Nutzer muss diese Informationen beispielsweise per E-Mail weitergeben.

IDs auf der Google Books-Website

Die IDs, die Sie mit der Books API verwenden, sind die gleichen wie auf der Google Books-Website.

  • Volume-ID

    Wenn Sie ein bestimmtes Volume auf der Website aufrufen, finden Sie die Volume-ID im URL-Parameter id. Hier ein Beispiel:

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • Bücherregal-ID

    Wenn du ein bestimmtes Bücherregal auf der Website aufrufst, findest du die Bücherregal-ID im URL-Parameter as_coll. Hier ein Beispiel:

    https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

  • Nutzer-ID

    Wenn du deine Mediathek auf der Website aufrufst, findest du die User-ID im URL-Parameter uid. Hier ein Beispiel:

    https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Standort des Nutzers festlegen

Google Books berücksichtigt Urheberrechte, Verträge und andere rechtliche Einschränkungen, die mit dem Standort des Endnutzers in Verbindung stehen. Deshalb können einige Nutzer möglicherweise aus bestimmten Ländern nicht auf Buchinhalte zugreifen. Beispielsweise können bestimmte Bücher nur in den USA in der Vorschau angesehen werden. Für Nutzer in anderen Ländern werden solche Vorschaulinks nicht angezeigt. Daher sind die API-Ergebnisse auf Grundlage der IP-Adresse Ihres Servers oder Ihrer Clientanwendung beschränkt.

Mit Volumes arbeiten

Suche durchführen

Sie können eine Volume-Suche durchführen, indem Sie eine HTTP-GET-Anfrage an den folgenden URI senden:

https://www.googleapis.com/books/v1/volumes?q=search+terms

Diese Anfrage hat einen einzigen erforderlichen Parameter:

  • q: Nach Volumes suchen, die diesen Textstring enthalten. Es gibt spezielle Suchbegriffe, die Sie in den Suchbegriffen angeben können, um in bestimmten Feldern zu suchen, z. B.:
    • intitle:Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Titel gefunden wird.
    • inauthor:Gibt Ergebnisse zurück, bei denen der Autor nach diesem Suchbegriff im Autor gefunden wurde.
    • inpublisher:Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Publisher gefunden wurde.
    • subject:Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword in der Kategorieliste des Volumes aufgeführt ist.
    • isbn:Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die ISBN-Nummer ist.
    • lccn: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die Library of Congress Control Number ist.
    • oclc:Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die Nummer des Online Computer Library Centers ist.

Anfragen

Hier ein Beispiel für die Suche nach Daniel Keyes&#t;Flowers for Algernon&quot:

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

Hinweis: Für eine Suche ist keine Authentifizierung erforderlich. Sie müssen daher den Authorization-HTTP-Header nicht mit der GET-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält jedes Volume nutzerspezifische Informationen, z. B. den Kaufstatus.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und den Volume-Ergebnissen:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

Optionale Abfrageparameter

Zusätzlich zu den standardmäßigen Abfrageparametern können Sie die folgenden Suchparameter verwenden, um eine Volumensuche durchzuführen.

Downloadformat

Verwenden Sie den Parameter download, um die zurückgegebenen Ergebnisse auf Volumes mit dem verfügbaren Downloadformat epub einzuschränken. Legen Sie dazu den auf den Wert epub fest.

Im folgenden Beispiel wird nach Büchern gesucht, für die ein EPUB-Download verfügbar ist:

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey
Filtern

Sie können den Parameter filter verwenden, um die zurückgegebenen Ergebnisse weiter einzuschränken. Legen Sie dazu einen der folgenden Werte fest:

  • partial: Gibt Ergebnisse zurück, bei denen mindestens Textabschnitte in der Vorschau angesehen werden können.
  • full: Gibt nur Ergebnisse zurück, bei denen der gesamte Text sichtbar ist.
  • free-ebooks: Gibt nur Ergebnisse zurück, die bei Google E-Books kostenlos sind.
  • paid-ebooks: gibt nur Ergebnisse zurück, bei denen es sich um E-Books von Google mit einem bestimmten Preis handelt.
  • ebooks: Gibt nur Ergebnisse zurück, die Google Books sind (kostenpflichtig oder kostenlos). Beispiele für Nicht-E-Books sind Inhalte von Verlagen und Webpublishern, die in einer eingeschränkten Vorschau verfügbar und nicht zum Verkauf verfügbar sind, oder Zeitschriften.

Im folgenden Beispiel werden Suchergebnisse auf die kostenlosen Bücher beschränkt:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey
Seitenumbruch

Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

  • startIndex: die Position in der Sammlung, an der der Ausgangspunkt beginnen soll. Der Index des ersten Elements ist 0.
  • maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Sie können den Parameter printType verwenden, um die zurückgegebenen Ergebnisse auf einen bestimmten Druck- oder Publikationstyp zu beschränken. Legen Sie dazu einen der folgenden Werte fest:

  • all – schränkt nicht nach Drucktyp ein (Standardeinstellung).
  • books: Gibt nur Ergebnisse von Büchern zurück.
  • magazines: Gibt Ergebnisse zurück, die Zeitschriften sind.

Im folgenden Beispiel werden Suchergebnisse auf Zeitschriften beschränkt:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Projection

Sie können den Parameter projection mit einem der folgenden Werte verwenden, um einen vordefinierten Satz von Volume-Feldern anzugeben, die zurückgegeben werden sollen:

  • full: Gibt alle Volume-Felder zurück.
  • lite: Gibt nur bestimmte Felder zurück. Welche Felder enthalten sind, entnehmen Sie der Feldbeschreibung mit doppelten Sternchen.

Im folgenden Beispiel werden Suchergebnisse mit begrenztem Volumen zurückgegeben:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey
Sortieren

Standardmäßig gibt eine Volume-Suchanfrage Ergebnisse vom Typ maxResults zurück, wobei maxResults der Parameter für die Paginierung (siehe oben) ist, sortiert nach der Relevanz für Suchbegriffe.

Sie können die Reihenfolge ändern, indem Sie den Parameter orderBy auf einen dieser Werte festlegen:

  • relevance: Gibt Ergebnisse in der Reihenfolge der Relevanz von Suchbegriffen zurück (Standardeinstellung).
  • newest: Gibt Ergebnisse in der Reihenfolge vom aktuellsten bis zum zuletzt veröffentlichten zurück.

Im folgenden Beispiel werden die Ergebnisse nach Veröffentlichungsdatum (neueste zuerst) aufgelistet:

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

Bestimmtes Volume abrufen

Sie können Informationen für ein bestimmtes Volume abrufen. Senden Sie dazu eine HTTP-GET-Anfrage an den URI der Volume-Ressource:

https://www.googleapis.com/books/v1/volumes/volumeId

Ersetzen Sie den Pfadparameter volumeId durch die ID des abzurufenden Volumes. Weitere Informationen zu Volume-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel für eine GET-Anfrage, die ein einzelnes Volume erhält:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

Hinweis: Das Abrufen von Volume-Informationen erfordert keine Authentifizierung. Sie müssen daher den Authorization-HTTP-Header nicht mit der GET-Anfrage angeben. Wenn der Aufruf jedoch mit Authentifizierung erfolgt, enthält das Volume nutzerspezifische Informationen wie den Kaufstatus.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der angeforderten Volume-Ressource:

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}
Zugriffsinformationen

Der Abschnitt accessInfo ist von besonderem Interesse, um zu bestimmen, welche Funktionen für ein E-Book verfügbar sind. epub ist ein E-Book mit Fließtextformat und im Abschnitt epub gibt es die Property isAvailable, die angibt, ob diese Art von E-Book verfügbar ist. Wenn es eine Leseprobe für das Buch gibt oder der Nutzer es entweder lesen kann, weil es gekauft wurde, oder weil es sich um eine urheberrechtsfreie Domain am Standort des Nutzers handelt, wird ein Downloadlink angezeigt. Ein pdf für Google-Bücher gibt eine gescannte Seitenversion des E-Books mit ähnlichen Details an, z. B. ob es verfügbar ist, und einen Downloadlink. Google empfiehlt epub-Dateien für E-Reader und Smartphones, da gescannte Seiten auf diesen Geräten möglicherweise schwer zu lesen sind. Wenn kein accessInfo-Abschnitt vorhanden ist, ist das Volume nicht als Google-E-Book verfügbar.

Optionale Abfrageparameter

Zusätzlich zu den Standard-Abfrageparametern können Sie beim Abrufen eines bestimmten Volumes den folgenden Abfrageparameter verwenden.

Projection

Sie können den Parameter projection mit einem der folgenden Werte verwenden, um einen vordefinierten Satz von Volume-Feldern anzugeben, die zurückgegeben werden sollen:

  • full: Gibt alle Volume-Felder zurück.
  • lite: Gibt nur bestimmte Felder zurück. Welche Felder enthalten sind, entnehmen Sie der Feldbeschreibung mit doppelten Sternchen.

Im folgenden Beispiel werden Informationen zu begrenztem Volumen für ein einzelnes Volume zurückgegeben:

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

Mit Bücherregalen arbeiten

Liste der öffentlichen Bücherregale eines Nutzers abrufen

Sie können eine Liste der öffentlichen Bücherregale eines Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

https://www.googleapis.com/books/v1/users/userId/bookshelves

Ersetzen Sie den Pfadparameter userId durch die ID des Nutzers, dessen Bücherregale Sie abrufen möchten. Weitere Informationen zu Nutzer-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den HTTP-Header Authorization nicht mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste der Bücherregale:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn Sie die Liste der öffentlichen Bücherregale eines Nutzers abrufen.

Bestimmtes öffentliches Bücherregal abrufen

Zum Abrufen eines bestimmten öffentlichen Bücherregales senden Sie eine HTTP-GET-Anfrage an den URI im folgenden Format:

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

Ersetzen Sie die Pfadparameter userId und shelf durch die IDs der Nutzer und des Regals, das abgerufen werden soll. Weitere Informationen findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den HTTP-Header Authorization nicht mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Bücherregal-Ressource:

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn ein bestimmtes öffentliches Bücherregal abgerufen wird.

Liste von Bänden in einem öffentlichen Bücherregal abrufen

Sie können eine Liste der Volumes im öffentlichen Bücherregal eines Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

Ersetzen Sie die Pfadparameter userId und shelf durch die IDs der Nutzer und des Regals, das abgerufen werden soll. Weitere Informationen findest du im Abschnitt Google Books-IDs.

Da ein Nutzer nicht authentifiziert sein muss, um Informationen zu öffentlichen Bücherregalen abzurufen, müssen Sie den HTTP-Header Authorization nicht mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit einem 200 OK-HTTP-Statuscode und der Liste der Bücherregale des Nutzers:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

Optionale Abfrageparameter

Zusätzlich zu den standardmäßigen Abfrageparametern können Sie beim Abrufen einer Liste von Volumes in einem öffentlichen Bücherregal den folgenden Abfrageparameter verwenden.

Seitenumbruch

Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

  • startIndex: die Position in der Sammlung, an der der Ausgangspunkt beginnen soll. Der Index des ersten Elements ist 0.
  • maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10 und der maximal zulässige Wert ist 40.

Bücherregale in "Meine Bibliothek" bearbeiten

Alle Anfragen aus „Meine Bibliothek“ gelten für die Daten des authentifizierten Nutzers.

Liste meiner Bücherregale abrufen

Sie können eine Liste aller Bücherregale des authentifizierten Nutzers abrufen, indem Sie eine HTTP-GET-Anfrage an den URI im folgenden Format senden:

https://www.googleapis.com/books/v1/mylibrary/bookshelves

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

Hinweis: Der Nutzer muss authentifiziert sein, um eine Liste von Bücherregalen abrufen zu können. Daher musst du den Authorization-HTTP-Header mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und der Liste aller Bücherregale für den aktuellen authentifizierten Nutzer:

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn Sie die Liste der Bücherregale des authentifizierten Nutzers abrufen.

Liste der Bände in meinem Bücherregal abrufen

Sie können eine Liste der Volumes im authentifizierten Bücherregal des authentifizierten Nutzers abrufen. Senden Sie dazu eine HTTP-GET-Anfrage an den URI im folgenden Format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel:

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

Hinweis: Der Nutzer muss authentifiziert sein, um eine Liste von Volumes in „Meine Bibliothek“ abzurufen. Daher musst du den Authorization-HTTP-Header mit der GET-Anfrage angeben.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und einer Liste der Bücherregal-Volumes:

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

Optionale Abfrageparameter

Zusätzlich zu den standardmäßigen Abfrageparametern können Sie den folgenden Abfrageparameter verwenden, wenn Sie eine Liste von Bänden in einem der authentifizierten Bücherregale eines Nutzers abrufen.

Seitenumbruch

Sie können die Volumes-Liste paginieren, indem Sie in den Parametern für die Anfrage zwei Werte angeben:

  • startIndex: die Position in der Sammlung, an der der Ausgangspunkt beginnen soll. Der Index des ersten Elements ist 0.
  • maxResults: Die maximale Anzahl der Ergebnisse, die zurückgegeben werden sollen. Der Standardwert ist 10.

Hinzufügen eines Bandes zu meinem Bücherregal

Wenn Sie dem Bücherregal des authentifizierten Nutzers ein Volume hinzufügen möchten, senden Sie eine HTTP-POST-Anfrage an den URI im folgenden Format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs findest du im Abschnitt Google Books-IDs.

Die Anfrage enthält nur einen erforderlichen Abfrageparameter:

  • volumeId: Die ID des Volumes. Weitere Informationen zu Volume-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ist ein Beispiel, wie Sie „Blumen für Algernon“ zum Bücherregal „Favoriten“ hinzufügen:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vorzunehmen. Daher müssen Sie den Authorization-HTTP-Header mit der POST-Anfrage angeben. Für dieses POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn Sie einem der Bücherregale des authentifizierten Nutzers ein Volume hinzufügen.

Volume aus meinem Bücherregal entfernen

Zum Entfernen eines Volumes aus dem Bücherregal des authentifizierten Nutzers senden Sie eine HTTP-POST an den URI im folgenden Format:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs findest du im Abschnitt Google Books-IDs.

Die Anfrage enthält nur einen erforderlichen Abfrageparameter:

  • volumeId: Die ID des Volumes. Weitere Informationen zu Volume-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

Hier ein Beispiel für das Entfernen von Blumen für Algernon aus dem Bücherregal „Favoriten“:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vorzunehmen. Daher müssen Sie den Authorization-HTTP-Header mit der POST-Anfrage angeben. Für dieses POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn Sie ein Volume aus einem der authentifizierten Bücherregale entfernen.

Alle Bände aus meinem Bücherregal löschen

Wenn Sie alle Volumes aus dem authentifizierten Bücherregal entfernen möchten, senden Sie eine HTTP-POST im folgenden Format an den URI:

https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes

Ersetzen Sie den Pfadparameter shelf durch die ID des Bücherregals. Weitere Informationen zu Bücherregal-IDs findest du im Abschnitt Google Books-IDs.

Anfragen

So löschen Sie das Bücherregal „Favoriten“:

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH
  

Hinweis: Der Nutzer muss authentifiziert sein, um Änderungen an einem Bücherregal vorzunehmen. Daher müssen Sie den Authorization-HTTP-Header mit der POST-Anfrage angeben. Für dieses POST sind jedoch keine Daten erforderlich.

Antwort

Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem Statuscode 204 No Content.

Optionale Abfrageparameter

Sie können die Standard-Abfrageparameter verwenden, wenn Sie alle Bände aus einem der Bücherregale des authentifizierten Nutzers löschen.

Abfrageparameterreferenz

Die Suchparameter, die Sie mit der Books API verwenden können, sind in diesem Abschnitt zusammengefasst.Alle Parameterwerte müssen URL-codiert sein.

Standardabfrageparameter

Abfrageparameter, die für alle Books API-Vorgänge gelten, sind unter Systemparameter dokumentiert.

API-spezifische Abfrageparameter

Anfrageparameter, die nur für bestimmte Vorgänge in der Books API gelten, sind in der folgenden Tabelle zusammengefasst.

Parameter Bedeutung Hinweise Geltungsbereich
download Auf Downloads anhand der Downloadverfügbarkeit beschränken
  • Derzeit wird nur epub unterstützt.
  • Für den Downloadzugriff ist möglicherweise ein Kauf erforderlich.
filter Suchergebnisse nach Volume-Typ und Verfügbarkeit filtern
  • Unterstützte Filter sind:
    • filter=partial: Die Ergebnisse lassen sich auf Bände beschränken, in denen zumindest ein Teil des Textes in der Vorschau angesehen werden kann.
    • filter=full: Die Ergebnisse lassen sich auf Bände beschränken, in denen der gesamte Text sichtbar ist.
    • filter=free-ebooks: Ergebnisse auf kostenlose Google E-Books beschränken.
    • filter=paid-ebooks – Schränken Sie Ergebnisse auf Google E-Books mit einem Preis für den Kauf ein.
    • filter=ebooks: Ergebnisse lassen sich auf kostenlose oder kostenpflichtige Google E-Books beschränken.Beispiele für Nicht-E-Books sind Inhalte von Verlagen und Webpublishern, die in einer eingeschränkten Vorschau verfügbar und nicht zum Verkauf verfügbar sind, oder Zeitschriften.

 

langRestrict Beschränkt die zurückgegebenen Volumes auf diejenigen, die mit der angegebenen Sprache getaggt sind.
  • Du kannst die Suchergebnisse auf Suchanfragen mit einer bestimmten Sprache beschränken. Gib dazu langRestrict auf einen aus zwei Buchstaben bestehenden ISO-639-1-Code an, z. B. "en" oder "fr".
maxResults Die maximale Anzahl von Elementen, die mit dieser Anfrage zurückgegeben werden sollen.
  • Für jede Anfrage für alle Elemente in einer Sammlung können Sie die Ergebnisse paginieren. Geben Sie dazu in den Parametern der Anfrage startIndex und maxResults an.
  • Standardwert: maxResults=10
  • Maximal zulässiger Wert: maxResults=40.
orderBy

Reihenfolge der Ergebnisse der Volumensuche.

  • Standardmäßig gibt eine Suchanfrage maxResults-Ergebnisse zurück, wobei maxResults der Parameter für die Paginierung ist, sortiert nach der zuerst relevantesten.
  • Sie können die Reihenfolge ändern, indem Sie den Parameter orderBy auf einen dieser Werte festlegen:
    • orderBy=relevance: Gibt Suchergebnisse in der von der relevantesten zur niedrigsten Priorität zurück (Standardeinstellung).
    • orderBy=newest: Gibt Suchergebnisse in der Reihenfolge des neuesten Veröffentlichungsdatums zurück (ältestes Datum).
printType Auf Bücher oder Zeitschriften beschränken
  • Unterstützte Werte:
    • printType=all: Gibt alle Inhaltstypen für Volumes zurück (keine Einschränkung). Das ist die Standardeinstellung.
    • printType=books – nur Bücher zurückgeben.
    • printType=magazines: nur Zeitschriften zurückgeben.
projection Beschränken Sie Volumeninformationen, die auf eine Teilmenge von Feldern zurückgegeben werden.
  • Unterstützte Projektionen sind:
    • projection=full: Enthält alle Volume-Metadaten (Standardeinstellung).
    • projection=lite: Enthält nur das Thema eines Volumes und Zugriffsmetadaten.
q Volltext-Abfragestring.
  • Wenn Sie eine Abfrage erstellen, geben Sie die entsprechenden Suchbegriffe durch „'+'“ im Format q=term1+term2_term3 ein. Alternativ können Sie sie durch ein Leerzeichen trennen. Wie bei allen Werten der Abfrageparameter müssen die Leerzeichen dann jedoch URL-codiert sein. Die API gibt alle Einträge zurück, die mit allen Suchbegriffen übereinstimmen (z. B. die Verwendung von UND zwischen Begriffen). Wie bei der Websuche von Google sucht die API nach vollständigen Wörtern (und ähnlichen Wörtern mit demselben Wortstamm), nicht nach Teilstrings.
  • Um nach einer genauen Wortgruppe zu suchen, setzen Sie die Wortgruppe in Anführungszeichen: q="exact phrase".
  • Wenn Sie Einträge ausschließen möchten, die mit einem bestimmten Begriff übereinstimmen, verwenden Sie das Formular q=-term.
  • Bei den Suchbegriffen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  • Beispiel: Wenn Sie nach allen Einträgen suchen möchten, die die genaue Wortgruppe "Elizabeth Bennet" und das Wort "Darcy" enthalten, aber nicht das Wort "Austen", verwenden Sie den folgenden Abfrageparameterwert:
    q="Elizabeth+Bennet"+Darcy-Austen
  • Es gibt spezielle Keywords, bei denen die Groß- und Kleinschreibung berücksichtigt werden muss. Sie können sie in den Suchbegriffen angeben, um in bestimmten Feldern zu suchen, z. B.:
    • intitle: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Titel gefunden wird.
    • inauthor: Gibt Ergebnisse zurück, bei denen der Text nach diesem Suchbegriff im Autor gefunden wurde.
    • inpublisher: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword im Publisher gefunden wird.
    • subject: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword in der Kategorieliste des Volumens aufgeführt ist.
    • isbn: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die ISBN-Nummer ist.
    • lccn: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die Library of Congress Control Number ist.
    • oclc: Gibt Ergebnisse zurück, bei denen der Text nach diesem Keyword die Nummer des Online Computer Library Centers ist.
startIndex Die Position in der Sammlung, an der die Liste der Ergebnisse gestartet werden soll.
  • Für jede Anfrage für alle Elemente in einer Sammlung können Sie die Ergebnisse paginieren. Geben Sie dazu in den Parametern der Anfrage startIndex und maxResults an.
  • Der Index des ersten Elements ist 0.
volumeId Kennzeichnet ein mit der Anfrage verknüpftes Volume.
  • Gibt die Lautstärke an, die einem Bücherregal hinzugefügt oder daraus entfernt werden soll.