Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Ce document vous aidera à vous familiariser avec l'API JSON Custom Search et son utilisation.
Avant de commencer
Créer un moteur Programmable Search Engine
En appelant l'API, l'utilisateur émet des requêtes sur une instance existante de Programmable Search Engine.
Par conséquent, avant d'utiliser l'API, vous devez en créer une dans le panneau de configuration. Suivez le tutoriel pour en savoir plus sur les différentes options de configuration.
Une fois le moteur créé, vous trouverez l'ID du moteur de recherche dans la section Général de la page Présentation. Il s'agit du paramètre cx utilisé par l'API.
Identifier votre application auprès de Google à l'aide d'une clé API
L'API JSON Custom Search nécessite l'utilisation d'une clé API. Une clé API permet d'identifier votre client auprès de Google.
Une fois que vous disposez d'une clé API, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête. Cette clé API peut être intégrée sans risque dans les URL et ne nécessite aucun encodage.
Présentation de l'API
Opérations de l'API
Il n'existe qu'une seule méthode à appeler dans l'API JSON Custom Search:
Renvoie les résultats de recherche demandés à partir d'un Programmable Search Engine.
GET
Modèle de données de l'API
Le résultat d'une requête de recherche envoyée à l'API JSON Custom Search est un objet JSON comprenant trois types de données:
Métadonnées décrivant la recherche demandée (et éventuellement les requêtes de recherche associée)
Métadonnées décrivant le Programmable Search Engine
Résultats de recherche
Pour en savoir plus, consultez la section "Données de réponse" de l'article Utiliser REST.
Le modèle de données est basé sur la spécification OpenSearch 1.1. En plus des propriétés OpenSearch standards, l'API JSON Custom Search définit deux propriétés personnalisées et deux rôles de requête personnalisés:
Propriétés personnalisées
cx: identifiant du Programmable Search Engine.
safe: description du niveau SafeSearch permettant de filtrer les résultats renvoyés.
Rôles associés aux requêtes personnalisées
nextPage: rôle indiquant que la requête peut être utilisée pour accéder à la page logique suivante des résultats, le cas échéant.
previousPage: rôle indiquant que la requête peut être utilisée pour accéder à la page logique de résultats précédente, le cas échéant.
Essayer
Pour tester les fonctionnalités de l'API sans écrire de code, consultez l'outil Essayer cette API.
Pour apprendre à utiliser l'API via des requêtes HTTP, passez à la section Utiliser REST.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/31 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Il n'y a pas l'information dont j'ai besoin","missingTheInformationINeed","thumb-down"],["Trop compliqué/Trop d'étapes","tooComplicatedTooManySteps","thumb-down"],["Obsolète","outOfDate","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Mauvais exemple/Erreur de code","samplesCodeIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 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)."]]
