Google Trends
Panoramica
Il Google Trends Connector fornisce accesso programmatico ai dati del servizio Google Trends. Consente ad agenti e applicazioni di ottenere informazioni sulla popolarità delle parole chiave, sulla distribuzione geografica dell'interesse, sulle ricerche attualmente di tendenza, sulle query correlate e sui suggerimenti di ricerca.
Il connettore supporta in particolare:
- analisi storica dell'interesse per le parole chiave,
- confronto di più parole chiave,
- ottenimento delle ricerche attualmente di tendenza,
- analisi di argomenti e query correlate,
- suggerimenti di ricerca (autocomplete).
Tutte le funzioni restituiscono dati strutturati ottenuti dall'API di Google Trends. Per gli endpoint delle ricerche di tendenza è implementato un fallback su una fonte RSS, nel caso in cui l'API primaria restituisca un errore o dati incompleti.
User story: Come un utente aggiunge il connettore Google Trends
1. L'utente apre la finestra di dialogo Aggiungi Connessione e seleziona GoogleTrends
- Nell'amministrazione, va alla sezione Connections / Connected Apps.
- Clicca su Add Connection.
- Nella lista dei connettori, seleziona la scheda GoogleTrends.
2. L'utente compila i dettagli del connettore
Nel modulo Dettagli, compila:
- Name: nome interno della connessione (ad es.
GoogleTrends). - Provide your ApiKey: chiave API, non richiesta in questa implementazione.
- Provide your Timezone: fuso orario (ad es.
UTC). - Provide your Language: lingua delle risposte (ad es.
EN, CS).
3. L'utente imposta i permessi delle singole funzioni
Dopo aver creato la connessione, imposta per ogni operazione la modalità di chiamata:
- Enabled,
- Enabled with confirmation,
- Disabled.
Raccomandazione: per le operazioni che possono influenzare l'esecuzione delle automazioni, impostare almeno su Enabled with confirmation.
4. L'utente salva e utilizza il connettore
Dopo il salvataggio, il connettore è disponibile per agenti e passaggi di workflow, dove è possibile chiamare specifiche funzioni di Google Trends in base ai permessi impostati.
Parametri di configurazione del connettore
| Parametro | Obbligatorio | Descrizione |
|---|---|---|
Name | Sì | Nome interno del connettore in Siesta AI |
ApiKey | In base all'implementazione | Chiave API per accedere al servizio |
Timezone | Sì | Fuso orario per le query (ad es. UTC) |
Language | Sì | Lingua dei risultati (ad es. EN, en-US) |
Funzioni supportate
1. GetInterestOverTimeAsync
Restituisce l'andamento dell'interesse per una o più parole chiave nel tempo.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keywords | string | Sì | Elenco di 1-5 parole chiave separate da virgola |
timeRange | string | No | Periodo di tempo per l'analisi |
geo | string | No | Area geografica (codice ISO del paese) |
category | int | No | Categoria di Google Trends |
Valori predefiniti:
timeRange:LastThreeMonthsgeo: globale (valore vuoto)category:0(tutte le categorie)
2. GetInterestByRegionAsync
Restituisce la distribuzione dell'interesse per una data parola chiave per regione.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword | string | Sì | Una parola chiave |
timeRange | string | No | Periodo di tempo |
resolution | string | No | Livello di risoluzione geografica |
geo | string | No | Codice del paese |
Valori predefiniti:
resolution:COUNTRYgeo:US
3. CompareKeywordsAsync
Confronta la popolarità di più parole chiave nel tempo.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keywords | string | Sì | Elenco di 2-5 parole chiave separate da virgola |
timeRange | string | No | Periodo di tempo |
geo | string | No | Codice del paese |
4. GetTrendingSearchesAsync
Restituisce le ricerche attualmente di tendenza.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
country | string | No | Nome del paese |
Valore predefinito:
country:united_states
Comportamento:
- Tentativo primario tramite l'API di Google Trends.
- In caso di fallimento, fallback su feed RSS.
5. GetTodaySearchesAsync
Restituisce le ricerche di tendenza di oggi.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
country | string | No | Codice del paese |
Valore predefinito:
country:US
Comportamento:
- Primariamente API, in caso di fallimento fallback su feed RSS.
6. GetAllTrendingSearchesAsync
Restituisce le ricerche di tendenza globalmente in più paesi.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| - | - | - | La funzione non richiede parametri |
Comportamento:
- tentativo di ottenere dati tramite API,
- fallback su feed RSS multi-paese.
7. GetRelatedQueriesAsync
Restituisce le query correlate a una data parola chiave.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword | string | Sì | Parola chiave |
timeRange | string | No | Periodo di tempo |
geo | string | No | Codice del paese |
L'output include:
Top queries(query correlate più frequenti),Rising queries(query in rapida crescita).
8. GetRelatedTopicsAsync
Restituisce argomenti correlati a una data parola chiave.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword | string | Sì | Parola chiave |
timeRange | string | No | Periodo di tempo |
geo | string | No | Codice del paese |
L'output include:
Top topics,Rising topics.
9. GetSuggestionsAsync
Restituisce suggerimenti di ricerca (autocomplete) per una parola chiave fornita.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
keyword | string | Sì | Parola chiave parziale o completa |
10. GetCategoriesAsync
Restituisce l'elenco completo delle categorie di Google Trends.
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| - | - | - | La funzione non richiede parametri |
Valori supportati per timeRange
timeRange è case-insensitive e supporta i seguenti valori:
| Valore | Descrizione |
|---|---|
LastHour | ultima ora |
LastFourHours | ultime 4 ore |
LastDay | ultime 24 ore |
LastWeek | ultimi 7 giorni |
LastMonth | ultimi 30 giorni |
LastThreeMonths | ultimi 90 giorni |
LastYear | ultimi 12 mesi |
LastFiveYears | ultimi 5 anni |
FromStart | tutti i dati storici disponibili |
Se il valore è non valido o mancante, verrà utilizzato il valore predefinito LastThreeMonths.
Contesto di Invocazione
Il comportamento del connettore può essere influenzato dal contesto di esecuzione:
| Campo | Valore predefinito | Descrizione |
|---|---|---|
Language | en-US | Lingua dei risultati |
Timezone | 300 | Offset del fuso orario in minuti |
Esempio:
Language: en-US
Timezone: 300
Strategie di fonti dati
Per gli endpoint che lavorano con le ricerche di tendenza, il recupero dei dati avviene in due fasi:
- Tentativo di recupero dei dati dall'API di Google Trends.
- Se l'API non risponde o restituisce dati incompleti, il sistema utilizza automaticamente il feed RSS di Google Trends.
Questo meccanismo garantisce una maggiore disponibilità dei dati.
Limiti
| Limite | Valore |
|---|---|
| Numero di parole chiave nella query | 1-5 |
| Confronto di parole chiave | 2-5 |
| Periodo di tempo predefinito | LastThreeMonths |
Riepilogo
Il connettore Google Trends è adatto per casi d'uso analitici, monitoraggio di argomenti, workflow di marketing e confronto delle tendenze nel tempo. Fornisce un'interfaccia unificata per lavorare con i dati di Google Trends, inclusa una strategia di fallback per le ricerche di tendenza.