Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
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:
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.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Benötigte Informationen nicht gefunden","missingTheInformationINeed","thumb-down"],["Zu umständlich/zu viele Schritte","tooComplicatedTooManySteps","thumb-down"],["Nicht mehr aktuell","outOfDate","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Problem mit Beispielen/Code","samplesCodeIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-31 (UTC)."],[[["\u003cp\u003eThis guide introduces the Custom Search JSON API and provides instructions for its use.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to create a Programmable Search Engine and obtain an API key.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows you to retrieve search results from your Programmable Search Engine using a single \u003ccode\u003elist\u003c/code\u003e operation.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns results in JSON format containing search metadata, engine details, and the search results themselves.\u003c/p\u003e\n"],["\u003cp\u003eYou can experiment with the API using the provided "Try this API" tool or learn more through detailed documentation and examples.\u003c/p\u003e\n"]]],[],null,["# Custom Search JSON API: Introduction\n\nThis document will help you to get familiar with Custom Search JSON API and its usage.\n\nBefore you start\n----------------\n\n### Create Programmable Search Engine\n\nBy calling the API user issues requests against an existing instance of\nProgrammable Search Engine.\nTherefore, before using the API, you need to create one in the\n[Control Panel](https://programmablesearchengine.google.com/controlpanel/create)\n. Follow the [tutorial](/custom-search/docs/tutorial/creatingcse)\nto learn more about different configuration options.\nOnce it is created, you can find the **Search Engine ID** in the **Overview**\npage's **Basic** section. This is the `cx` parameter used by the API.\n\n### Identify your application to Google with API key\n\nCustom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.\n\n- [Programmable Search Engine](https://cse.google.com/) (free edition) users: Get a Key\n\nAfter you have an API key, your application can append the query parameter\n`key=yourAPIKey` to all request URLs. The API key is safe for embedding in URLs,\nit doesn't need any encoding.\n\nAPI overview\n------------\n\n### API operations\n\nThere is only one method to invoke in the Custom Search JSON API:\n\n| Operation | Description | REST HTTP mapping |\n|------------------------------------------------------|-------------------------------------------------------------------------|-------------------|\n| [list](/custom-search/v1/reference/rest/v1/cse/list) | Returns the requested search results from a Programmable Search Engine. | `GET` |\n\n### API data model\n\nThe result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nSee the Response data section of [Using REST](/custom-search/v1/using_rest#response_data) for more details.\n\nThe data model is based on the OpenSearch 1.1 Specification. In addition to the standard OpenSearch properties, the Custom Search JSON API defines two custom properties and two custom query roles:\n\n- Custom properties\n - `cx`: The identifier of the Programmable Search Engine.\n - `safe`: A description of the safe search level for filtering the returned results.\n- Custom query roles\n - `nextPage`: A role that indicates the query can be used to access the next logical page of results, if any.\n - `previousPage`: A role that indicates the query can be used to access the previous logical page of results, if any.\n\nTry it\n------\n\nTo play around and see what the API can do, without writing any code, visit the\n[\"Try this API\" tool](/custom-search/v1/reference/rest/v1/cse/list?apix=true).\n\nFor a full description of parameters visit the\n[cse.list reference](/custom-search/v1/reference/rest/v1/cse/list).\n\nTo learn how to use the API via HTTP requests, continue to\n[Using REST](/custom-search/v1/using_rest)."]]
