Custom Search JSON API: Einführung

In diesem Dokument werden die Custom Search JSON API und ihre Verwendung erläutert.

Vorbereitung

Programmable Search Engine erstellen

Durch den Aufruf der API stellen Nutzer Anfragen an eine vorhandene Instanz der Programmable Search Engine. Bevor Sie die API verwenden können, müssen Sie daher im Steuerfeld eine Suchmaschine erstellen. Folgen Sie der Anleitung, um mehr über die verschiedenen Konfigurationsoptionen zu erfahren. Nachdem sie erstellt wurde, finden Sie die Suchmaschinen-ID auf der Seite Übersicht im Bereich Basisdaten. Dies ist der Parameter cx, der von der API verwendet wird.

Anwendung mit API-Schlüssel gegenüber Google identifizieren

Für die Custom Search JSON API ist ein API-Schlüssel erforderlich. Mit einem API-Schlüssel können Sie Ihren Client gegenüber Google identifizieren.

Sobald Sie einen API-Schlüssel haben, kann Ihre Anwendung den Suchparameter key=yourAPIKey an alle Anfrage-URLs anhängen. Der API-Schlüssel kann sicher in URLs eingebettet werden und muss nicht codiert werden.

API-Übersicht

API-Vorgänge

In der Custom Search JSON API gibt es nur eine Methode, die aufgerufen werden kann:

Vorgang Beschreibung REST-HTTP-Zuordnung
list Gibt die angeforderten Suchergebnisse einer Programmable Search Engine zurück. GET

API-Datenmodell

Das Ergebnis einer Suchanfrage an die Custom Search JSON API ist ein JSON-Objekt, das drei Arten von Daten enthält:

  • Metadaten, die die angeforderte Suche (und möglicherweise ähnliche Suchanfragen) beschreiben
  • Metadaten, die die Programmable Search Engine beschreiben
  • Suchergebnisse

Weitere Informationen finden Sie im Abschnitt „Antwortdaten“ unter REST verwenden.

Das Datenmodell basiert auf der OpenSearch 1.1-Spezifikation. Zusätzlich zu den standardmäßigen OpenSearch-Eigenschaften definiert die Custom Search JSON API zwei benutzerdefinierte Eigenschaften und zwei benutzerdefinierte Abfragerollen:

  • Benutzerdefinierte Eigenschaften
    • cx: Die Kennung der Programmable Search Engine.
    • safe: Eine Beschreibung der SafeSearch-Stufe zum Filtern der zurückgegebenen Ergebnisse.
  • Benutzerdefinierte Abfragerollen
    • nextPage: Eine Rolle, die angibt, dass die Abfrage verwendet werden kann, um auf die nächste logische Ergebnisseite zuzugreifen, falls vorhanden.
    • previousPage: Eine Rolle, die angibt, dass die Abfrage verwendet werden kann, um auf die vorherige logische Seite mit Ergebnissen zuzugreifen, falls vorhanden.

Ausprobieren

Wenn Sie die API ausprobieren und sehen möchten, was sie kann, ohne Code zu schreiben, rufen Sie das Tool „Diese API testen“ auf.

Eine vollständige Beschreibung der Parameter finden Sie in der Referenz zu cse.list.

Informationen zur Verwendung der API über HTTP-Anfragen finden Sie unter REST verwenden.