REST zum Aufrufen der API verwenden

In diesem Dokument wird die Verwendung der Custom Search JSON API beschrieben.

Anfragen senden

REST (Representational State Transfer) in der Custom Search JSON API unterscheidet sich etwas von der herkömmlichen REST. 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 zugehörigen URI senden. Dabei übergeben Sie die Details der Suchanfrage als Abfrageparameter. Der URI der Custom Search JSON API hat folgendes Format:

https://www.googleapis.com/customsearch/v1?[parameters]

Bei jeder Suchanfrage sind drei [parameters]-Abfragen erforderlich:

  • API-Schlüssel: Verwenden Sie den Abfrageparameter key, um Ihre Anwendung zu identifizieren.
  • Programmable Search Engine ID: Geben Sie mit cx die Programmable Search Engine an, 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).

  • Suchanfrage: Verwenden Sie den Abfrageparameter q, um den Suchausdruck anzugeben.

Alle anderen Abfrageparameter sind optional.

Hier sehen Sie ein Beispiel für eine Anfrage, bei der in einer Test-Programmable Search Engine nach Lektionen gesucht wird:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Abfrageparameter

Es gibt zwei Arten von Parametern, die Sie in Ihrer Anfrage übergeben können:

  • API-spezifische Parameter – Definieren Sie Attribute Ihrer Suche wie Suchausdruck, Anzahl der Ergebnisse, 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 Antwortdatenstruktur finden Sie in der Referenz.

Die Antwortdaten sind ein JSON-Objekt mit drei Arten von Attributen:

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

Eine ausführliche Beschreibung der einzelnen Attribute finden Sie in der Referenz.

Metadaten der Suchanfrage

Die Metadaten der Suche umfassen:

  • url mit Informationen zur OpenSearch-Vorlage, die für die in dieser Anfrage zurückgegebenen Ergebnisse verwendet wird.
  • Die Eigenschaft queries ist ein Array von Objekten, die die Merkmale möglicher Suchvorgänge beschreiben. Der Name jedes Objekts im Array ist entweder der Name einer OpenSearch-Abfragerolle oder eine der beiden von dieser API definierten benutzerdefinierten Rollen: previousPage und nextPage. Zu den möglichen Abfragerollenobjekten gehören:
    • request: Metadaten, die die Abfrage für die aktuellen Ergebnisse beschreiben.
      • Diese Rolle ist in der Antwort immer vorhanden.
      • Es ist immer ein Array mit nur einem Element.
      • nextPage: Metadaten zur Beschreibung der Abfrage, die für die nächste Ergebnisseite verwendet werden soll.
        • Diese Rolle ist nicht vorhanden, wenn die aktuellen Ergebnisse die letzte Seite sind. Hinweis : Diese API gibt nur bis zu die ersten 100 Ergebnisse zurück.
        • Wenn vorhanden, ist es immer ein Array mit nur einem Element.
    • previousPage: Metadaten zur Beschreibung der Abfrage, die für die vorherige Ergebnisseite verwendet werden soll.
      • 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 zur Beschreibung der Suchmaschine, die die Suchanfrage ausgeführt hat. Sie enthält den Namen der Suchmaschine sowie alle Attributobjekte, die sie zum Verfeinern einer Suche bereitstellt.

Suchergebnisse

Das Array items enthält die eigentlichen Suchergebnisse. Die Suchergebnisse enthalten die URL, den Titel und die Text-Snippets, die das Ergebnis beschreiben. Gegebenenfalls können sie auch Rich Snippet-Informationen enthalten.

Wenn die Suchergebnisse die Property promotions enthalten, enthält diese eine Reihe von Angeboten.

REST aus JavaScript

Sie können die Custom Search JSON API über REST aus JavaScript aufrufen. Verwenden Sie dazu den Abfrageparameter callback und eine Callback-Funktion. So können Sie umfangreiche Anwendungen schreiben, die Daten der Programmable Search Engine anzeigen, ohne serverseitigen Code schreiben zu müssen.

Im folgenden Beispiel wird mit diesem Ansatz die erste Seite der Suchergebnisse für die Suchanfrage cars angezeigt:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; 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=cars&callback=hndlr">
    </script>
  </body>
</html>