Ce document explique comment utiliser l'API JSON Custom Search.
Envoyer une requête
REST, ou Representational State Transfer, dans l'API JSON Custom Search est quelque peu différent 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 du 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 requis 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 Programmable Search Engine que vous souhaitez 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 être de 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 conférences dans un moteur de recherche programmable 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éfinissez les propriétés de votre recherche, comme 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 qui 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 comprend 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 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 les éléments suivants:
- La propriété
url, qui contient des informations sur le modèle OpenSearch utilisé pour les résultats renvoyés dans cette requête. - Propriété
queries, qui est un tableau d'objets décrivant les caractéristiques des recherches possibles. Le nom de chaque objet du tableau correspond au nom d'un rôle de requête OpenSearch ou à l'un des deux rôles personnalisés définis par cette API :previousPageetnextPage. Voici les objets de rôle de requête possibles :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.- Indisponible 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 comprend le nom du moteur de recherche et 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. En outre, elles peuvent contenir des informations de extraits enrichis, le cas échéant.
Si les résultats de recherche incluent une propriété promotions, ils contiennent un ensemble de promotions.
REST à partir de JavaScript
Vous pouvez appeler l'API JSON Custom Search à l'aide de REST depuis JavaScript, à l'aide du paramètre de requête callback et d'une fonction de rappel. Vous pouvez ainsi écrire des applications riches qui affichent des données 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>