Ricerca X per il Marketing: Handle, Date e Filtri
In questa pagina
Trasforma X in uno Strumento di Monitoraggio Marketing
X (ex Twitter) rimane una delle piattaforme più ricche di dati di marketing azionabili in tempo reale. Con lo strumento x_search nelle API di Grok, puoi interrogare questa massa di informazioni in modo strutturato, filtrato e automatizzabile, direttamente dalle tue applicazioni o script.
A differenza della ricerca manuale su X, le API ti permettono di colpire con precisione account, periodi e argomenti specifici. Per un responsabile marketing, significa passare da un monitoraggio artigianale a un sistema programmabile di raccolta di intelligence competitiva.
Abilita la Ricerca X nelle API di Grok
Abiliti lo strumento x_search dichiarandolo nell’array tools della tua richiesta API. Funziona esclusivamente con le API Responses (l’endpoint legacy Chat Completions è deprecato per la ricerca).
from openai import OpenAI
client = OpenAI(
api_key="your-xai-key",
base_url="https://api.x.ai/v1"
)
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Quali sono gli ultimi post di @nike sulle loro campagne marketing?",
tools=[{"type": "x_search"}]
)
Il modello decide automaticamente quando avviare una ricerca su X in base alla tua domanda. Non devi gestire manualmente l’attivazione.
Filtra per Handle: Mira ad Account Specifici
Il parametro allowed_x_handles ti permette di limitare la ricerca a un massimo di 10 account X specifici. È lo strumento ideale per monitorare i tuoi diretti concorrenti o partner.
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Riassumi gli annunci di prodotto di questi brand questa settimana",
tools=[{
"type": "x_search",
"allowed_x_handles": [
"nike", "adidas", "puma",
"newbalance", "reebok"
]
}]
)
Al contrario, excluded_x_handles ti permette di escludere fino a 10 account dai risultati. Nota: questi due parametri sono mutuamente esclusivi (non puoi combinarli nella stessa richiesta).
Casi d’Uso Marketing
- Monitoraggio competitivo: traccia i 5–10 account dei tuoi diretti concorrenti
- Partnership: segui i post dei tuoi partner e ambassador
- Ecosistema: escludi i tuoi account per vedere solo il mercato
Filtra per Date: Isola un Periodo
I parametri from_date e to_date accettano date in formato ISO 8601 (AAAA-MM-GG). Questo ti permette di mirare a una campagna specifica, a un evento di settore o di confrontare due periodi.
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Analizza le reazioni alla campagna Black Friday di questi brand",
tools=[{
"type": "x_search",
"allowed_x_handles": ["amazon_fr", "cdiscount", "fnac"],
"from_date": "2025-11-25",
"to_date": "2025-12-02"
}]
)
Questa combinazione di handle + date ti offre un ambito di ricerca estremamente preciso, paragonabile a un brief di ricerca di mercato automatizzato.
Comprendi Immagini e Video nei Post
Due parametri booleani arricchiscono il tuo monitoraggio visivo:
enable_image_understanding: il modello analizza le immagini contenute nei post (visual di campagne, infografiche, screenshot)enable_video_understanding: il modello interpreta i video (spot pubblicitari, teaser di prodotto, dimostrazioni)
tools=[{
"type": "x_search",
"allowed_x_handles": ["apple"],
"enable_image_understanding": True,
"enable_video_understanding": True
}]
Per un marketer, questo significa che Grok può descrivere i visual pubblicitari dei tuoi concorrenti, identificare i codici colore utilizzati o riassumere il contenuto di un video promozionale, tutto in modo programmabile.
Pratica: Script di Monitoraggio Settimanale
Ecco uno script completo che genera un report di monitoraggio settimanale sui tuoi concorrenti:
from datetime import datetime, timedelta
# Calcola la settimana passata
today = datetime.now().strftime("%Y-%m-%d")
last_week = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="""Analizza i post di questi brand dell'ultima settimana.
Per ogni brand, identifica:
1. I principali annunci di prodotto
2. Le campagne marketing lanciate
3. Il tono e il posizionamento utilizzati
4. I post che hanno generato più engagement""",
tools=[{
"type": "x_search",
"allowed_x_handles": [
"concurrent1", "concurrent2", "concurrent3"
],
"from_date": last_week,
"to_date": today,
"enable_image_understanding": True
}]
)
print(response.output_text)
Punti chiave
- La Ricerca X costa $5 per 1.000 chiamate, rendendola uno strumento di monitoraggio molto accessibile
- Puoi filtrare per handle (max 10) o date (formato ISO 8601), o combinare entrambi
allowed_x_handlesedexcluded_x_handlessono mutuamente esclusivi- L’analisi di immagini e video nei post è esclusiva della Ricerca X (non disponibile nella Ricerca Web)
- Usa le API Responses (non Chat Completions, deprecate per la ricerca)