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 envoie des requêtes à une instance existante de Programmable Search Engine. Par conséquent, avant d'utiliser l'API, vous devez en créer un dans le panneau de configuration. Suivez le tutoriel pour en savoir plus sur les différentes options de configuration. Une fois le moteur de recherche créé, vous trouverez l'ID du moteur de recherche dans la section Basique de la page Présentation. Il s'agit du paramètre cx utilisé par l'API.
Identifier votre application auprès de Google avec 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. La clé API peut être intégrée aux URL en toute sécurité, elle ne nécessite aucun encodage.
Présentation de l'API
Opérations d'API
Il n'existe qu'une seule méthode à appeler dans l'API JSON Custom Search :
| Opération | Description | Mappage HTTP REST |
|---|---|---|
| liste | Renvoie les résultats de recherche demandés à partir d'un moteur de recherche programmable. | 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 qui inclut trois types de données :
- Métadonnées décrivant la recherche demandée (et, éventuellement, les requêtes de recherche associées)
- Métadonnées décrivant le moteur Programmable Search Engine
- Résultats de recherche
Pour en savoir plus, consultez la section "Données de réponse" de 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 moteur de recherche programmable.safe: description du niveau de SafeSearch pour filtrer les résultats renvoyés.
- Rôles de requête personnalisés
nextPage: rôle indiquant que la requête peut être utilisée pour accéder à la page de résultats logique suivante, le cas échéant.previousPage: rôle indiquant que la requête peut être utilisée pour accéder à la page logique précédente des résultats, le cas échéant.
Essayer
Pour tester l'API et voir ce qu'elle peut faire sans écrire de code, consultez l'outil "Essayer cette API".
Pour obtenir une description complète des paramètres, consultez la documentation de référence sur cse.list.
Pour savoir comment utiliser l'API via des requêtes HTTP, consultez Utiliser REST.