Passa al contenuto principale

Google Search API

Siesta AI - Google Search consente di eseguire programmaticamente ricerche web tramite Google Custom Search JSON API. La connessione è in sola lettura e restituisce JSON strutturato con i risultati.

1. Configurazione di Google Search API (procedura pratica)​

  1. Progetto in Google Cloud: utilizza un progetto esistente o creane uno nuovo.
  2. Abilita Custom Search API: nella API Library cerca "Custom Search API" e clicca Enable. Attivazione Custom Search API nella API Library
  3. Crea Programmable Search Engine: su https://programmablesearchengine.google.com/ apri l'elenco dei motori di ricerca e clicca Aggiungi. Elenco dei motori di ricerca in Programmable Search Engine Creazione di un nuovo motore di ricerca
  4. Ottieni l'ID del motore di ricerca (cx): nei dettagli del motore di ricerca apri la sezione Base e copia ID del motore di ricerca. Copia dell'ID del motore di ricerca (cx)
  5. Genera API Key: nella Google Cloud Console -> APIs & Services -> Credentials -> Crea credenziali -> API key. Creazione della chiave API in Credentials
  6. Restrizioni della chiave (consigliato):
    • Restrizioni applicative: secondo necessità (Nessuna/Siti Web/IP).
    • Restrizioni API: Restrict key -> Custom Search API.
  7. Impostazioni in Siesta AI:
    • Connessione -> Aggiungi Connessione -> GoogleSearch.
    • Compila Key (API Key) e Cx (ID del motore di ricerca) e scegli Condiviso/Privato.
    • Salva tramite Continua. Impostazioni della Connessione GoogleSearch in Siesta AI

2. Scopo del documento​

L'obiettivo è consentire l'accesso programmatico ai risultati delle ricerche web tramite Google Custom Search JSON API.

3. Panoramica della Connessione​

  • Nome della Connessione: GoogleSearch
  • Tipo: REST API - Google Custom Search JSON API
  • Autenticazione: API Key (Google Cloud) + ID del motore di ricerca (cx) (OAuth non necessario)
  • Scope: solo read/search
  • Output: oggetto JSON con i risultati della ricerca
  • Nota: Non esistono operazioni di scrittura; tutte le chiamate sono idempotenti.

Google Custom Search JSON API consente di ottenere programmaticamente risultati di ricerca da Google tramite Programmable Search Engine, che deve essere creato e configurato prima dell'uso.

4. Principi generali​

4.1 Configurazione​

  • ID del motore di ricerca (cx): identificatore della propria istanza di ricerca.
  • API Key: parametro obbligatorio per le chiamate autorizzate all'API di Google.
  • Output: JSON contiene metadati di ricerca e set di risultati (title, snippet, URL, pagemap, ecc.).

4.2 Sintassi di query​

  • Il parametro query (alias q) determina l'espressione da cercare.
  • Possono essere utilizzati operatori avanzati come site:, intitle: ecc. (sintassi di query standard di Google).

5. Operazioni API​

5.1 Ricerca​

Descrizione: Esegue una ricerca web tramite Google Custom Search JSON API.
HTTP: GET https://www.googleapis.com/customsearch/v1?key={API_KEY}&cx={SEARCH_ENGINE_ID}&q={query}

ParametroTipoObbligatorioDescrizione
queryStringSìEspressione da cercare (es. "AI best practices").

Output

  • Elenco dei risultati (title, URL, snippet)
  • Metadati sul numero di risultati
  • Eventuali ulteriori blocchi (pagemap)

Comportamento e limiti

  • Risposta standard ~10 risultati per pagina; ulteriori pagine tramite start (fuori dallo scope della Connessione).

Errori tipici

  • 400 Bad Request - query non valida
  • 401 Unauthorized - API Key non valida
  • 403 Quota Exceeded - quota giornaliera superata

6. Sicurezza e governance​

  • Conserva l'API Key in modo sicuro; preferisci restrizioni (domini/IP, limitazioni su Custom Search API).
  • Monitora le quote e registra per il controllo della fatturazione.
  • Registra almeno: stringa query, ora della chiamata, numero di risultati, stato HTTP.

7. Raccomandazioni operative​

  • Imposta una politica di rotazione per l'API Key (Rotate key nella Google Cloud Console).
  • Mantieni cx e API Key in un segreto sicuro; aggiorna la Connessione in caso di modifica della chiave.

8. Esempio di utilizzo​

GET https://www.googleapis.com/customsearch/v1
  ?key=YOUR_API_KEY
  &cx=YOUR_SEARCH_ENGINE_ID
  &q=cloud+infrastructure+best+practices

JSON abbreviato:

{
  "queries": { "request": [ { "query": "cloud infrastructure best practices" } ] },
  "items": [
    { "title": "...", "link": "...", "snippet": "..." }
  ]
}