Ce document explique comment utiliser l'API JSON Custom Search.
Envoyer une requête
L'architecture REST (Representational State Transfer) de l'API JSON Custom Search est quelque peu différente des API RESTful habituelles. Au lieu de fournir un accès aux ressources, l'API fournit un accès à un service. Par conséquent, l'API fournit un URI unique qui sert de point de terminaison de service.
Vous pouvez récupérer les résultats d'une recherche spécifique 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 [parameters] de requête sont obligatoires pour chaque requête de recherche :
Clé API : utilisez le paramètre de requête
keypour identifier votre application.- ID Programmable Search Engine : utilisez
cxpour spécifier le moteur de recherche Programmable Search Engine que vous souhaitez utiliser pour effectuer cette recherche. Le moteur de recherche doit être créé avec le panneau de configuration. Remarque : L'ID du moteur de recherche (cx) peut être dans un format différent (par exemple, 8ac1ab64606d234f1).
- ID Programmable Search Engine : utilisez
Requête de recherche : utilisez le paramètre de requête
qpour 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 cours dans un Programmable Search Engine de test :
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesParamètres de requête
Vous pouvez transmettre deux types de paramètres dans votre requête :
- Paramètres spécifiques à l'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, comme la clé API.
Toutes les valeurs de paramètre doivent être encodées au format URL.
Paramètres de requête spécifiques à l'API
Les paramètres de requête qui s'appliquent spécifiquement à l'API JSON Custom Search et définissent votre requête de recherche sont résumé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 répertoriés sur la page Paramètres système.
Données de réponse
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 consulter 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ées)
- Métadonnées décrivant le moteur 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 la requête de recherche
Les métadonnées de recherche incluent :
- La propriété
url, qui contient des informations sur le modèle OpenSearch utilisé pour les résultats renvoyés dans cette requête. - La propriété
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 :previousPageetnextPage. Les objets de rôle de requête possibles sont les suivants :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 ne contenant qu'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'il est présent, il s'agit toujours d'un tableau ne contenant qu'un seul élément.
previousPage: métadonnées décrivant la requête à utiliser pour la page de résultats précédente.- Non présent si les résultats actuels correspondent à la première page.
- Lorsqu'il est présent, il s'agit toujours d'un tableau ne contenant qu'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 de facette 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 décrivent le résultat. Ils peuvent également contenir des informations sur les extraits enrichis, le cas échéant.
Si les résultats de recherche incluent une propriété promotions, elle contient un ensemble de promotions.
REST à partir de JavaScript
Vous pouvez appeler l'API JSON Custom Search à l'aide de REST à partir de JavaScript, en utilisant le paramètre de requête callback et une fonction de rappel. Vous pouvez ainsi créer des applications enrichies qui affichent les données de Programmable Search Engine sans avoir à écrire de code côté serveur.
L'exemple suivant utilise cette approche pour afficher la première page des résultats de recherche pour la requête lecture :
<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
<div id="content"></div>
<p id="demo"></p>
<script>
function hndlr(response) {
if (response.items == null) {
document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
} else {
for (var i = 1; 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=lecture&callback=hndlr">
</script>
</body>
</html>