Trasformare Google Trends in un segnale di domanda con Python

Vuoi un numero che dica quanto interesse sta ricevendo un argomento in questo momento, da mettere in una dashboard, per decidere cosa tenere a magazzino, o cosa scrivere per primo. Leggere un grafico a linee sul sito di Google Trends non scala oltre un lookup alla volta, e non si inserisce da nessuna parte dove uno script possa usarlo.

Cosa restituisce /v1/trends

Manda una query a /v1/trends e ricevi interest_over_time, e al suo interno una lista timeline_data. Ogni punto ha una date (un intervallo leggibile tipo “Aug 23-29, 2026”), un timestamp, e una lista values con una voce per ogni query che hai chiesto, ciascuna con un value da 0 a 100. Il nostro campione, per la query “web scraping api”, è tornato con 53 punti settimanali su circa un anno, per 5 crediti.

Il numero è relativo, mai assoluto

Qui è dove si sbaglia più spesso: un value di Trends non è un conteggio di ricerche. È un indice, scalato in modo che il punto più alto nell’intervallo che hai chiesto sia 100 e ogni altro punto sia una frazione di quel picco. Un valore di 14 non significa 14 ricerche o 14 di qualcosa di contabile. Significa il 14 percento di qualunque cosa fosse la settimana più intensa in quella finestra.

Questo ha due conseguenze che sfuggono a molti. Primo, non puoi confrontare il valore di una query con il valore di una query diversa e concludere che un argomento viene cercato di più, perché ciascuno è scalato sul proprio picco, non su una base condivisa. Secondo, un valore calcolato su un intervallo di date o una località non è comparabile con un valore calcolato su un intervallo diverso, per lo stesso motivo: cambi la finestra e ogni punto viene riscalato su un nuovo picco. Se ti servono due argomenti sulla stessa scala, chiedili insieme in un’unica chiamata così condividono una base, oppure confronta la forma (in salita, in discesa, piatta) invece del livello grezzo.

Leggere la serie e una direzione di tendenza

import requests

API_KEY = "faf_live_..."  # la tua chiave FastAF

resp = requests.get(
    "https://api.fastaf.co/v1/trends",
    params={"query": "web scraping api", "data_type": "TIMESERIES"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
resp.raise_for_status()

points = resp.json()["interest_over_time"]["timeline_data"]
series = [(p["date"], p["values"][0]["value"]) for p in points]

for date, value in series[-8:]:
    print(f"{date:<26} {value:>3}")

recent = [v for _, v in series[-8:]]
prior = [v for _, v in series[-16:-8]]
recent_avg = sum(recent) / len(recent)
prior_avg = sum(prior) / len(prior)
change = (recent_avg - prior_avg) / prior_avg * 100
direction = "rising" if change > 10 else "falling" if change < -10 else "flat"

print(f"recent avg {recent_avg:.1f} vs prior avg {prior_avg:.1f}: {direction} ({change:+.1f}%)")

Sul nostro campione questo ha stampato le ultime otto settimane, che rimbalzano tra 5 e 88, con una media recente di 37,9 contro una media delle otto settimane precedenti di 84,6: un calo del 55 percento, etichettato “falling”. Se otto settimane sia la finestra giusta dipende da come si muove normalmente l’argomento. Una categoria che si muove più lentamente potrebbe confrontare blocchi di 90 giorni invece di due da 8 settimane; la forma del calcolo resta la stessa.

Usarlo davvero

Una riga di dashboard ha bisogno solo dell’ultimo value e dell’etichetta di direzione, aggiornati con la cadenza che corrisponde a quanto spesso si muove davvero l’interesse sottostante: giornaliero è eccessivo per una serie che riporta solo a blocchi settimanali, come il nostro campione. Per decidere cosa tenere a magazzino o cosa scrivere, la direzione conta più del livello assoluto: un argomento che sale da 20 a 40 è un segnale più chiaro di un argomento fermo a 80 da mesi, anche se 80 suona come il numero più grande.

Quanto costa

Una chiamata costa 5 crediti, indipendentemente da quante settimane torna la serie, quindi riempire una dashboard con un anno di storico e aggiornarla ogni settimana costano entrambi gli stessi 5 crediti. Le richieste fallite non vengono addebitate.

Inizia con il piano gratuito, 500 crediti senza carta, cioè 100 chiamate: abbastanza per tirare giù la serie di ogni argomento tra cui stai decidendo, prima di impegnarti a tracciarne uno.