Cette page a été traduite par l'API Cloud Translation.

Utiliser REST pour appeler l'API

Ce document explique comment utiliser l'API JSON Custom Search.

Envoyer une demande

REST, ou Representational State Transfer, dans l'API JSON Custom Search est légèrement différent de REST traditionnel. Au lieu de fournir l'accès aux ressources, l'API permet d'accéder à un service. Par conséquent, l'API fournit un URI unique qui sert de point de terminaison du service.

Vous pouvez récupérer les résultats d'une recherche particulière en envoyant une requête HTTP GET à son URI. Vous transmettez les détails de la requête de recherche en tant que paramètres de requête. Le format de l'URI de l'API JSON Custom Search est le suivant:

https://www.googleapis.com/customsearch/v1?[parameters]

Trois requêtes [parameters] sont requises pour chaque requête de recherche:

Clé API : utilisez le paramètre de requête key pour identifier votre application.
ID Programmable Search Engine : utilisez cx pour spécifier le Programmable Search Engine à utiliser pour effectuer cette recherche. Le moteur de recherche doit être créé à l'aide du Panneau de configuration.Remarque: L'ID du moteur de recherche (cx) peut se présenter sous un format différent (par exemple, 8ac1ab64606d234f1).
Requête de recherche : utilisez le paramètre de requête q pour spécifier votre expression de recherche.

Tous les autres paramètres de requête sont facultatifs.

Voici un exemple de requête qui recherche des lectures dans un Programmable Search Engine de test:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Paramètres de requête

Vous pouvez transmettre deux types de paramètres dans votre requête:

Paramètres spécifiques aux API : définissent les propriétés de votre recherche, telles que l'expression de recherche, le nombre de résultats, la langue, etc.
Paramètres de requête standards : définissent les aspects techniques de votre requête, tels que la clé API.

Toutes les valeurs de paramètre doivent être encodées au format URL.

Paramètres de requête spécifiques aux API

Les paramètres de requête qui s'appliquent spécifiquement à l'API JSON Custom Search et qui définissent votre requête de recherche sont récapitulés dans la documentation de référence.

Paramètres de requête standards

Les paramètres de requête qui s'appliquent à toutes les opérations de l'API JSON Custom Search sont documentés sur la page Paramètres système.

Données des réponses

Si la requête aboutit, le serveur répond avec un code d'état HTTP 200 OK et les données de réponse au format JSON. Vous pouvez rechercher la structure des données de réponse dans la documentation de référence.

Les données de réponse sont un objet JSON qui inclut trois types de propriétés:

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 obtenir une description détaillée de chaque propriété, consultez la documentation de référence.

Métadonnées de requête de recherche

Les métadonnées de recherche incluent:

url, qui contient des informations sur le modèle OpenSearch utilisé pour les résultats renvoyés dans cette requête.
queries, qui est un tableau d'objets décrivant les caractéristiques des recherches possibles. Le nom de chaque objet du tableau est soit le nom d'un rôle de requête OpenSearch, soit l'un des deux rôles personnalisés définis par cette API : previousPage et nextPage. Les objets possibles du rôle de requête incluent :
- request: métadonnées décrivant la requête pour l'ensemble de résultats actuel.
  - Ce rôle est toujours présent dans la réponse.
  - Il s'agit toujours d'un tableau comportant un seul élément.
  - nextPage: métadonnées décrivant la requête à utiliser pour la page de résultats suivante.
    - Ce rôle n'est pas présent si les résultats actuels correspondent à la dernière page. Remarque : Cette API ne renvoie que les 100 premiers résultats.
    - Lorsqu'elle est présente, il s'agit toujours d'un tableau contenant un seul élément.
- previousPage: métadonnées décrivant la requête à utiliser pour la page de résultats précédente.
  - Indisponible si les résultats actuels correspondent à la première page.
  - Lorsqu'elle est présente, il s'agit toujours d'un tableau contenant un seul élément.

Métadonnées du moteur de recherche

La propriété context contient des métadonnées décrivant le moteur de recherche qui a effectué la requête de recherche. Il inclut le nom du moteur de recherche et tous les objets d'attribut qu'il fournit pour affiner une recherche.

Résultats de recherche

Le tableau items contient les résultats de recherche réels. Les résultats de recherche incluent l'URL, le titre et les extraits de texte qui les décrivent. Elles peuvent également contenir des extraits enrichis, le cas échéant.

Si les résultats de recherche incluent une propriété promotions, celle-ci contient un ensemble de promotions.

REST à partir de JavaScript

Vous pouvez appeler l'API JSON Custom Search en utilisant REST à partir de JavaScript, en utilisant le paramètre de requête callback et une fonction de rappel. Vous pouvez ainsi écrire des applications enrichies qui affichent des données Programmable Search Engine sans écrire de code côté serveur.

L'exemple suivant utilise cette approche pour afficher la première page de résultats de recherche pour la requête cars:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // Make sure HTML in item.htmlTitle is escaped.
        document.getElementById("content").append(
          document.createElement("br"),
          document.createTextNode(item.htmlTitle)
        );
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>