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 un peu différente de l'API REST traditionnelle. Au lieu de fournir un accès aux ressources, l'API fournit un accès à un service. Par conséquent, l'API fournit un seul URI qui fait office de point de terminaison du service.
Vous pouvez récupérer les résultats d'une recherche particulière en envoyant un GET HTTP
à 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
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'identifiant du moteur de recherche (cx) peut avoir différents formats (par exemple, 8ac1ab64606d234f1).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 permettant de rechercher Test Programmable Search Engine pour les lectures:
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 propres à l'API : définissez les propriétés de votre recherche, par exemple l'expression de recherche, le nombre de résultats, la langue, etc.
- Paramètres de requête standards : ils définissent les aspects techniques de votre requête, tels que le Clé API.
Toutes les valeurs des paramètres doivent être encodées au format URL.
Paramètres de requête spécifiques à l'API
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 section 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 indiqués sur la page Paramètres système.
Données de réponse
Si la requête aboutit, le serveur affiche un code d'état HTTP 200 OK.
et les données de réponse au format JSON. Vous pouvez rechercher les données de réponse
dans la 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 référence.
Métadonnées de requête de recherche
Les métadonnées de recherche incluent les éléments suivants:
url, qui possède des informations sur le modèle OpenSearch utilisée pour les résultats renvoyés dans cette requête.queries, qui est un tableau de des objets décrivant les caractéristiques des recherches possibles. Le nom de chaque du tableau est le nom d'un Rôle de requête OpenSearch ou l'un des deux rôles personnalisés définis par cette API:previousPageetnextPage. Objets de rôle de requête possibles incluent: <ph type="x-smartling-placeholder">- </ph>
request: métadonnées décrivant la requête pour l'ensemble actuel de résultats.- Ce rôle est toujours présent dans la réponse.
- Il s'agit toujours d'un tableau ne comportant qu'un seul élément.
nextPage: métadonnées décrivant la requête à utiliser pour la requête suivante page de résultats.- 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 comportant qu'un seul élément.
previousPage: métadonnées décrivant la requête à utiliser pour la sur la page de résultats précédente.- Non présente si les résultats actuels correspondent à la première page.
- Lorsqu'il est présent, il s'agit toujours d'un tableau ne comportant qu'un seul élément.
Métadonnées du moteur de recherche
La propriété context comporte des métadonnées décrivant le moteur de recherche.
ayant exécuté la requête de recherche. Elle comprend le nom du moteur de recherche
tous les objets de facettes qu'il fournit
en affinant une recherche.
Résultats de recherche
Le tableau items contient les résultats de recherche réels. La recherche
les résultats comprennent l'URL, le titre et les extraits de texte décrivant le résultat. Dans
Ils peuvent également contenir un extrait enrichi
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, à l'aide de la méthode
Paramètre de requête callback et une fonction de rappel. Cela vous permet
pour créer des applications enrichies qui affichent des données Programmable Search Engine sans écrire
code côté serveur.
L'exemple suivant utilise cette approche pour afficher la première page des résultats de recherche résultats de 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>