API JSON Custom Search: introduction

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.