Questo documento descrive come utilizzare l'API Custom Search JSON.
Fai una richiesta
REST, o Representational State Transfer, nell' API Custom Search JSON è leggermente diverso dalle normali API RESTful. Anziché fornire accesso alle risorse, l'API fornisce l'accesso a un servizio. Di conseguenza, l'API fornisce un unico URI che funge da endpoint del servizio.
Puoi recuperare i risultati di una determinata ricerca inviando una richiesta HTTP GET
al relativo URI. Devi passare i dettagli della richiesta di ricerca come parametri di query. Il formato dell'URI dell'API Custom Search JSON è:
https://www.googleapis.com/customsearch/v1?[parameters]
Per ogni richiesta di ricerca sono necessarie tre query [parameters]:
Chiave API: utilizza il parametro di query
keyper identificare la tua applicazione.- ID Motore di ricerca programmabile: utilizza
cxper specificare il Motore di ricerca programmabile che vuoi utilizzare per eseguire questa ricerca. Il motore di ricerca deve essere creato con il pannello di controllo. Nota: l'ID motore di ricerca (cx) può essere di formato diverso (ad es. 8ac1ab64606d234f1).
- ID Motore di ricerca programmabile: utilizza
Query di ricerca: utilizza il parametro di query
qper specificare l'espressione di ricerca.
Tutti gli altri parametri di query sono facoltativi.
Ecco un esempio di richiesta che cerca lezioni in un Motore di ricerca programmabile di prova:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesParametri di query
Esistono due tipi di parametri che puoi passare nella richiesta:
- Parametri specifici dell'API: definiscono le proprietà della ricerca, ad esempio l'espressione di ricerca, il numero di risultati, la lingua e così via.
- Parametri di query standard: definiscono aspetti tecnici della richiesta, come la chiave API.
Tutti i valori dei parametri devono essere codificati nell'URL.
Parametri di query specifici dell'API
I parametri di richiesta che si applicano specificamente all'API Custom Search JSON e definiscono la richiesta di ricerca sono riportati nella pagina di documentazione.
Parametri di query standard
I parametri di query che si applicano a tutte le operazioni dell'API Custom Search JSON sono descritti in Parametri di sistema.
Dati di risposta
Se la richiesta riesce, il server risponde con un codice di stato HTTP 200 OK e i dati di risposta in formato JSON. Puoi cercare la struttura dei dati di risposta nel documento di riferimento.
I dati di risposta sono un oggetto JSON che include tre tipi di proprietà:
- Metadati che descrivono la ricerca richiesta (e, eventualmente, le richieste di ricerca correlata)
- Metadati che descrivono il Motore di ricerca programmabile
- Risultati di ricerca
Per una descrizione dettagliata di ogni proprietà, consulta la documentazione di riferimento.
Metadati della richiesta di ricerca
I metadati di ricerca includono:
url, che contiene informazioni sul modello OpenSearch utilizzato per i risultati restituiti in questa richiesta.- La proprietà
queries, che è un array di oggetti che descrivono le caratteristiche delle possibili ricerche. Il nome di ogni oggetto nell'array è il nome di un ruolo di query OpenSearch o uno dei due ruoli personalizzati definiti da questa API:previousPageenextPage. I possibili oggetti ruolo query includono:request: metadati che descrivono la query per l'insieme di risultati corrente.- Questo ruolo è sempre presente nella risposta.
- È sempre un array con un solo elemento.
nextPage: metadati che descrivono la query da utilizzare per la pagina successiva di risultati.- Questo ruolo non è presente se i risultati attuali sono l'ultima pagina. Nota: questa API restituisce solo i primi 100 risultati.
- Se presente, è sempre un array con un solo elemento.
previousPage: metadati che descrivono la query da utilizzare per la pagina di risultati precedente.- Non presente se i risultati attuali sono la prima pagina.
- Se presente, è sempre un array con un solo elemento.
Metadati dei motori di ricerca
La proprietà context contiene metadati che descrivono il motore di ricerca che ha eseguito la query di ricerca. Include il nome del motore di ricerca e tutti gli oggetti
delle sfaccettature che fornisce per perfezionare una
spolvero.
Risultati di ricerca
L'array items contiene i risultati di ricerca effettivi. I risultati di ricerca includono
l'URL, il titolo e gli snippet di testo che descrivono il risultato. Inoltre, possono contenere informazioni sui rich snippet, se applicabili.
Se i risultati di ricerca includono una proprietà promotions, questa contiene un insieme di
promozioni.
REST da JavaScript
Puoi richiamare l'API Custom Search JSON utilizzando REST da JavaScript, con il parametro di query callback e una funzione di callback. In questo modo puoi scrivere applicazioni ricche che mostrano i dati di Programmable Search Engine senza scrivere codice lato server.
L'esempio seguente utilizza questo approccio per visualizzare la prima pagina dei risultati di ricerca per la query 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>