Mithilfe dieses Dokuments können Sie sich mit der Custom Search JSON API und ihrer Verwendung vertraut machen.
Vorbereitung
Programmable Search Engine erstellen
Durch Aufrufen des API-Nutzers werden Anfragen an eine vorhandene Instanz der Programmable Search Engine gesendet.
Bevor Sie die API verwenden können, müssen Sie daher eine im Steuerfeld erstellen. Folgen Sie der Anleitung, um mehr über die verschiedenen Konfigurationsoptionen zu erfahren.
Nach der Erstellung finden Sie die Suchmaschinen-ID im Abschnitt Grundlagen auf der Seite Übersicht. Dies ist der cx-Parameter, der von der API verwendet wird.
Anwendung mit einem API-Schlüssel bei Google identifizieren
Für die JSON API für die benutzerdefinierte Suche ist die Verwendung eines API-Schlüssels erforderlich. Ein API-Schlüssel ist eine Möglichkeit, Ihren Kunden gegenüber Google zu identifizieren.
Sobald Sie einen API-Schlüssel haben, kann die Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen. Der API-Schlüssel kann problemlos in URLs eingebettet werden und erfordert keine Codierung.
API-Übersicht
API-Vorgänge
In der Custom Search JSON API kann nur eine Methode aufgerufen werden:
| Vorgang | Beschreibung | REST-HTTP-Zuordnung |
|---|---|---|
| list | Gibt die angeforderten Suchergebnisse von 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 Datentypen enthält:
- Metadaten, die die angeforderte Suche (und möglicherweise ähnliche Suchanfragen) beschreiben
- Metadaten zur Beschreibung der Programmable Search Engine
- Suchergebnisse
Weitere Informationen finden Sie im Abschnitt zu Antwortdaten unter REST verwenden.
Das Datenmodell basiert auf der Spezifikation OpenSearch 1.1. Zusätzlich zu den OpenSearch-Standardeigenschaften 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-Ebene zum Filtern der zurückgegebenen Ergebnisse.
- Benutzerdefinierte Abfragerollen
nextPage: Eine Rolle, die angibt, dass die Abfrage für den Zugriff auf die nächste logische Seite mit Ergebnissen verwendet werden kann, 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 sich mit der API vertraut machen möchten, ohne Code schreiben zu müssen, rufen Sie das Tool „API testen“ auf.
Eine vollständige Beschreibung der Parameter finden Sie in der Referenz zu cse.list.
Wie Sie die API über HTTP-Anfragen nutzen, erfahren Sie unter REST verwenden.