Utilizzo di REST per richiamare l'API

Questo documento descrive come utilizzare l'API JSON Custom Search.

Presentazione di una richiesta

REST, o Representational State Transfer, nell'API JSON Custom Search è leggermente diverso dal tradizionale REST. Anziché fornire l'accesso alle risorse, l'API fornisce l'accesso a un servizio. Di conseguenza, l'API fornisce un singolo URI che funge da endpoint di servizio.

Puoi recuperare i risultati per una determinata ricerca inviando una richiesta GET HTTP al relativo URI. Puoi trasmettere i dettagli della richiesta di ricerca come parametri di ricerca. Il formato dell'URI JSON Custom Search dell'API è:

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

Per ogni richiesta di ricerca sono necessarie tre query [parameters]:

  • Chiave API: utilizza il parametro di query key per identificare l'applicazione.

  • ID motore di ricerca programmabile: utilizza cx per 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ò avere un formato diverso (ad es. 8ac1ab64606d234f1).

  • Query di ricerca: utilizza il parametro di query q per specificare l'espressione di ricerca.

Tutti gli altri parametri di query sono facoltativi.

Ecco un esempio di richiesta che cerca le lezioni in un Motore di ricerca programmabile di test:

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

Parametri di ricerca

Esistono due tipi di parametri che puoi trasmettere nella richiesta:

  • Parametri specifici dell'API: definiscono le proprietà della ricerca, come l'espressione di ricerca, il numero di risultati, la lingua e così via
  • Parametri di query standard: definisci gli aspetti tecnici della richiesta, ad esempio la chiave API.

Tutti i valori dei parametri devono essere codificati nell'URL.

Parametri di query specifici dell'API

I parametri della richiesta che si applicano specificamente all'API JSON Custom Search e definiscono la tua richiesta di ricerca sono riepilogati nel riferimento.

Parametri di query standard

I parametri di ricerca che si applicano a tutte le operazioni dell'API JSON Custom Search sono documentati in Parametri di sistema.

Dati delle risposte

Se la richiesta ha esito positivo, 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 delle risposte nel riferimento.

I dati della risposta sono un oggetto JSON che include tre tipi di proprietà:

  • Metadati che descrivono la ricerca richiesta (e possibilmente le richieste di ricerca correlata)
  • Metadati che descrivono il Motore di ricerca programmabile
  • Risultati di ricerca

Per una descrizione dettagliata di ciascuna proprietà, consulta il riferimento.

Metadati delle richieste di ricerca

I metadati della ricerca includono:

  • url, che contiene informazioni sul modello OpenSearch utilizzato per i risultati restituiti in questa richiesta.
  • 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 query OpenSearch o uno dei due ruoli personalizzati definiti da questa API: previousPage e nextPage. I possibili oggetti con ruolo di query includono:
    • request: metadati che descrivono la query per l'insieme di risultati attuale.
      • Questo ruolo è sempre presente nella risposta.
      • È sempre un array con un solo elemento.
      • nextPage: metadati che descrivono la query da utilizzare per la pagina dei risultati successiva.
        • 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 dei risultati precedente.
      • Non presente se i risultati correnti sono la prima pagina.
      • Se presente, è sempre un array con un solo elemento.

Metadati del motore di ricerca

La proprietà context include 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 facet che fornisce per perfezionare una ricerca.

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 relative ai 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 JSON Custom Search utilizzando REST da JavaScript, usando il parametro di query callback e una funzione di callback. Ciò ti consente di scrivere applicazioni avanzate che visualizzano i dati di Motore di ricerca programmabile senza scrivere alcun codice lato server.

L'esempio seguente utilizza questo approccio per visualizzare la prima pagina dei risultati di ricerca per la query auto:

<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>