API über REST aufrufen

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

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 dient.

Sie können Ergebnisse für eine bestimmte Suche abrufen, indem Sie eine HTTP-GET-Anfrage an den URI senden. Sie geben die Details der Suchanfrage als Abfrageparameter ein. Das Format für die Custom Search JSON API-URI:

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

Für jede Suchanfrage sind drei Abfrage-[parameters] erforderlich:

• API-Schlüssel: Mit dem Abfrageparameter key können Sie Ihre Anwendung identifizieren.

  • Programmable Search Engine-ID: Mit cx können Sie die Programmable Search Engine angeben, die Sie für diese Suche verwenden möchten. Die Suchmaschine muss über das 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 Suchparameter sind optional.

Hier ein Beispiel für eine Anfrage, bei der in einer Test-Programmable Search Engine nach Vorträgen 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 du in deiner Anfrage übergeben kannst:

• API-spezifische Parameter: Hiermit werden Eigenschaften der Suche definiert, z. B. der Suchbegriff, die Anzahl der Ergebnisse oder die Sprache.
• Standardabfrageparameter: Hiermit werden technische Aspekte Ihrer Anfrage definiert, z. B. der 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 Custom Search JSON API-Vorgänge 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 Properties:

• Metadaten, die die angeforderte Suche (und gegebenenfalls zugehörige Suchanfragen) beschreiben
• Metadaten, die die Programmable Search Engine beschreiben
• Suchergebnisse

Eine detaillierte Beschreibung der einzelnen Properties finden Sie in der Referenz.

Metadaten der Suchanfrage

Die Suchmetadaten umfassen:

• url-Attribut mit Informationen zur OpenSearch-Vorlage, die für die in dieser Anfrage zurückgegebenen Ergebnisse verwendet wird.
• Die Property queries ist ein Array von Objekten, die die Eigenschaften möglicher Suchanfragen beschreiben. Der Name jedes Objekts im Array ist entweder der Name einer OpenSearch-Abfragerolle oder einer der beiden benutzerdefinierten Rollen, die von dieser API definiert sind: previousPage und nextPage. Mögliche Objekte für die Abfragerolle:
  • 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 beschreiben, 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 die ersten 100 Ergebnisse zurück.
      • Wenn vorhanden, ist es immer ein Array mit nur einem Element.
  • previousPage: Metadaten, die die Abfrage beschreiben, 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.

Suchmaschinenmetadaten

Das Attribut context enthält Metadaten, die die Suchmaschine beschreiben, mit der die Suchanfrage ausgeführt wurde. Es enthält den Namen der Suchmaschine und alle Facettenobjekte, die zum Eingrenzen einer Suche verwendet werden können.

Suchergebnisse

Das Array items 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 eine promotions-Property enthalten, enthält sie eine Reihe von Angeboten.

REST aus JavaScript

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

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

<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>