In diesem Dokument wird die Verwendung der Custom Search JSON API erläutert.
Anfrage stellen
REST (Representational State Transfer) in der Custom Search JSON API unterscheidet sich etwas von den üblichen RESTful APIs. Anstatt Zugriff auf Ressourcen zu gewähren, bietet die API Zugriff auf einen Dienst. Daher stellt die API einen einzelnen URI bereit, der als Dienstendpunkt fungiert.
Sie können Ergebnisse für eine bestimmte Suche abrufen, indem Sie eine HTTP-GET-Anfrage an den URI senden. Sie übergeben die Details der Suchanfrage als Abfrageparameter. Das Format für die Custom Search JSON API-URI lautet:
https://www.googleapis.com/customsearch/v1?[parameters]
Für jede Suchanfrage sind drei Abfrage-[parameters] erforderlich:
API-Schlüssel: Verwenden Sie den Suchparameter
key, um Ihre Anwendung zu identifizieren.- Programmable Search Engine-ID: Verwenden Sie
cx, um die Programmable Search Engine anzugeben, die Sie für diese Suche verwenden möchten. Die Suchmaschine muss mit dem Steuerfeld erstellt werden. Hinweis: Die Suchmaschinen-ID (cx) kann ein anderes Format haben (z. B. 8ac1ab64606d234f1).
- Programmable Search Engine-ID: Verwenden Sie
Suchanfrage: Verwenden Sie den Abfrageparameter
q, um Ihren Suchausdruck anzugeben.
Alle anderen Abfrageparameter sind optional.
Hier ist ein Beispiel für eine Anfrage, bei der in einer Test-Programmable Search Engine nach lectures gesucht wird:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesSuchparameter
Es gibt zwei Arten von Parametern, die Sie in Ihrer Anfrage übergeben können:
- API-spezifische Parameter: Definieren Sie Eigenschaften Ihrer Suche, z. B. den Suchausdruck, die Anzahl der Ergebnisse, die Sprache usw.
- Standardabfrageparameter: Definieren technische Aspekte Ihrer Anfrage, z. B. den API-Schlüssel.
Alle Parameterwerte müssen URL-codiert sein.
API-spezifische Abfrageparameter
Anfrageparameter, die speziell für die Custom Search JSON API gelten und Ihre Suchanfrage definieren, sind in der Referenz zusammengefasst.
Standardabfrageparameter
Abfrageparameter, die für alle Vorgänge der Custom Search JSON API gelten, sind unter Systemparameter dokumentiert.
Antwortdaten
Wenn die Anfrage erfolgreich ist, antwortet der Server mit dem HTTP-Statuscode 200 OK und den Antwortdaten im JSON-Format. Die Datenstruktur der Antwort finden Sie in der Referenz.
Die Antwortdaten sind ein JSON-Objekt, das drei Arten von Attributen enthält:
- Metadaten, die die angeforderte Suche (und möglicherweise ähnliche Suchanfragen) beschreiben
- Metadaten, die die Programmable Search Engine beschreiben
- Suchergebnisse
Eine detaillierte Beschreibung der einzelnen Attribute finden Sie in der Referenz.
Metadaten der Suchanfrage
Die Suchmetadaten umfassen:
url-Attribut, das Informationen zur OpenSearch-Vorlage enthält, die für die in dieser Anfrage zurückgegebenen Ergebnisse verwendet wurde.queries-Property, ein Array von Objekten, die die Merkmale möglicher Suchanfragen beschreiben. Der Name jedes Objekts im Array ist entweder der Name einer OpenSearch-Abfragerolle oder eine der beiden benutzerdefinierten Rollen, die von dieser API definiert werden:previousPageundnextPage. Mögliche Abfragerollenobjekte:request: Metadaten, die die Abfrage für die aktuellen Ergebnisse beschreiben.- Diese Rolle ist immer in der Antwort enthalten.
- Es ist immer ein Array mit nur einem Element.
nextPage: Metadaten, die die Abfrage für die nächste Ergebnisseite beschreiben.- Diese Rolle ist nicht vorhanden, wenn die aktuellen Ergebnisse die letzte Seite sind. Hinweis: Diese API gibt nur die ersten 100 Ergebnisse zurück.
- Wenn vorhanden, ist es immer ein Array mit nur einem Element.
previousPage: Metadaten, die die Abfrage für die vorherige Ergebnisseite beschreiben.- Nicht vorhanden, wenn die aktuellen Ergebnisse die erste Seite sind.
- Wenn vorhanden, ist es immer ein Array mit nur einem Element.
Suchmaschinen-Metadaten
Das Attribut context enthält Metadaten, die die Suchmaschine beschreiben, die die Suchanfrage ausgeführt hat. Sie enthält den Namen der Suchmaschine und alle Facettenobjekte, die sie zum Verfeinern einer Suche bereitstellt.
Suchergebnisse
Das items-Array enthält die tatsächlichen Suchergebnisse. Die Suchergebnisse enthalten die URL, den Titel und Text-Snippets, die das Ergebnis beschreiben. Außerdem können sie gegebenenfalls Rich Snippet-Informationen enthalten.
Wenn die Suchergebnisse das Attribut promotions enthalten, enthält es eine Reihe von Angeboten.
REST aus JavaScript
Sie können die Custom Search JSON API mit REST aus JavaScript aufrufen, indem Sie den Suchparameter callback und eine Callback-Funktion verwenden. So können Sie umfangreiche Anwendungen schreiben, die Programmable Search Engine-Daten anzeigen, ohne serverseitigen Code schreiben zu müssen.
Im folgenden Beispiel wird dieser Ansatz verwendet, um die erste Seite mit Suchergebnissen für die Abfrage lecture anzuzeigen:
<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
<div id="content"></div>
<p id="demo"></p>
<script>
function hndlr(response) {
if (response.items == null) {
document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
} else {
for (var i = 1; i < response.items.length; i++) {
var item = response.items[i];
// Make sure HTML in item.htmlTitle is escaped.
document.getElementById("content").append(
document.createElement("br"),
document.createTextNode(item.htmlTitle)
);
}
}
}
</script>
<script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=lecture&callback=hndlr">
</script>
</body>
</html>