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.
- Utilisateurs de Programmable Search Engine (édition sans frais) : obtenir une clé
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:
| Opération | Description | Mappage HTTP REST |
|---|---|---|
| liste | 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 obtenir une description complète des paramètres, consultez la documentation de référence sur CSe.list.
Pour apprendre à utiliser l'API via des requêtes HTTP, passez à la section Utiliser REST.