Il brand monitoring di solito parte da due domande: dove si parla di noi sul web, e con quale tono? La prima richiede dati a livello di pagina da leggere e smistare. La seconda richiede un dato aggregato da mettere in grafico senza scaricare milioni di pagine.
Il 2026-11-17 SocQ ha lanciato la piattaforma Brand Monitoring con un endpoint per ciascuna domanda. Questa guida spiega cosa restituiscono, come si fanno le richieste, quanto costano e quando usare ciascuno.
Risposta rapida: invia un brand, un prodotto o un argomento in
queryaPOST /v1/brand-monitoring/mentionsper ottenere un elenco di pagine web che lo menzionano, ognuna con punteggi di sentiment, emozioni e autorevolezza. Invia la stessaqueryaPOST /v1/brand-monitoring/sentimentper ottenere una riga che suddivide tutte le menzioni per sentiment ed emozione. InterrogaGET /v1/tasks/{task_id}per i risultati.
I nuovi endpoint di Brand Monitoring
1 credito SocQ = $0.005.
| Endpoint | Cosa restituisce | Prezzo |
|---|---|---|
| Brand Mentions API | Una riga per ogni pagina web che menziona la query: URL, titolo, passaggio attorno alla menzione, autore, lingua, paese, tipo di sito, punteggi di sentiment ed emozioni, autorevolezza della pagina e del dominio | 10 crediti ($0.05) per richiesta + 0.02 crediti ($0.0001) per pagina |
| Brand Sentiment Analysis API | Una riga che raggruppa tutte le pagine che menzionano la query per sentiment principale e per emozione più forte, con il numero di pagine e i siti, paesi, lingue e tipi di sito principali di ogni gruppo | 10 crediti ($0.05) per chiamata |
Per Brand Mentions il costo base di 10 crediti si applica anche quando non viene trovata nessuna pagina.
Autenticazione e flusso asincrono delle attività
Tutte le richieste SocQ si autenticano con una chiave API, e lo stesso header vale per l’invio, lo stato dell’attività e le richieste dei risultati:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ogni raccolta viene eseguita come attività in background:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La risposta all’invio contiene data.task_id e data.status. Interroga l’attività con quell’ID:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Quando status è succeeded, la risposta include la prima pagina di record normalizzati in data.results.items. limit vale 50 per impostazione predefinita e arriva fino a 500; se has_more è true, passa results.next_cursor come cursor per leggere la pagina successiva. Mentre un’attività è queued, running o failed, l’endpoint restituisce i metadati dell’attività senza results.
Un callback_url facoltativo nel corpo dell’invio fa sì che SocQ invii un’unica POST con un riepilogo al termine dell’attività; leggi i record con GET /v1/tasks/{task_id}. Un timeout lato client non annulla l’attività, quindi riprendi con lo stesso ID invece di pagare un duplicato. 402 indica crediti insufficienti; 429 indica che la chiave ha raggiunto un limite di frequenza o di crediti.
Brand Mentions API: tutte le pagine che ti menzionano
La Brand Mentions API restituisce pagine da tutto il web che menzionano la tua query: recensioni sui blog, articoli di giornale, discussioni nei forum e schede prodotto. Inserisci un brand, un prodotto o un argomento in query, fino a 100 caratteri. Racchiudi una frase tra virgolette doppie per cercarla esatta. content_type limita i risultati ai siti news, blogs, message-boards, ecommerce o organization. results_limit vale 100 per impostazione predefinita e accetta valori da 1 a 1,000.
curl -X POST "https://api.socq.ai/v1/brand-monitoring/mentions" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "notion",
"results_limit": 100
}'
Ogni riga descrive una pagina:
- Dove:
url,title,domain,language,country(due lettere;WWsignifica mondo intero) epage_types, per esempionews,blogsoecommerce. - Cosa:
text, il passaggio attorno alla menzione, eauthor_namequando indicato. - Con quale tono:
sentimentcon punteggipositive,negativeeneutralda 0 a 1 che sommati danno 1, edemotionscon sei punteggi da 0 a 1:happiness,love,fun,share,sadnesseanger. - Quanto conta:
content_quality_score(da 0 a 100),spam_score(da 0 a 100, più è alto più segnali di spam ci sono),domain_rankepage_rank(da 0 a 1,000). - Quando:
fetched_at, il momento dell’ultima lettura della pagina.
I punteggi di autorevolezza e di spam ti permettono di ordinare un grande insieme di risultati, così il team legge per prime le pagine molto autorevoli e con poco spam, mentre la suddivisione del sentiment segnala le pagine che richiedono una risposta. 100 pagine costano 12 crediti ($0.06), e il massimo di 1,000 pagine costa 30 crediti ($0.15). Elenco completo dei campi: documentazione di Brand Mentions.
Per seguire solo la stampa, aggiungi un filtro:
{
"query": "\"notion ai\"",
"content_type": "news",
"results_limit": 200
}
Brand Sentiment Analysis API: la suddivisione dietro il numero
La Brand Sentiment Analysis API risponde alla domanda "come ci percepisce il web" senza restituire le singole pagine. Le pagine che menzionano la tua query vengono raggruppate per sentiment principale e, separatamente, per emozione più forte. Ogni gruppo riporta quante pagine contiene e i siti, i paesi, le lingue e i tipi di sito che contribuiscono di più.
curl -X POST "https://api.socq.ai/v1/brand-monitoring/sentiment" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "notion"
}'
L’unica riga di risultato contiene due array:
sentiments: un gruppo ciascuno perpositive,negativeeneutral.emotions: un gruppo ciascuno perhappiness,love,fun,share,sadnesseanger.
Ogni gruppo ha un label, un mentions_count e top_domains, countries, languages e page_types, ciascuno un elenco di name e count, dal più grande. Questa struttura ti permette di capire se le critiche arrivano dalle testate giornalistiche o da un singolo forum, e quali paesi le alimentano. Ogni richiesta costa 10 crediti ($0.05). I termini molto generici con milioni di menzioni richiedono più tempo di analisi, fino a qualche minuto, quindi interroga l’attività con pazienza. Consulta la documentazione di Brand Sentiment Analysis.
Quale endpoint usare
- Una dashboard settimanale della reputazione: esegui Brand Sentiment Analysis per il tuo brand e per ogni concorrente, salva i conteggi e mettili in grafico nel tempo. Quattro brand costano 40 crediti ($0.20) per esecuzione.
- Una coda di smistamento per il team comunicazione: esegui Brand Mentions con
content_typeimpostato sunewsomessage-boards, poi ordina per sentimentnegativee perdomain_rank. - Indagare un picco: quando i conteggi del sentiment cambiano, usa i
top_domainsdel gruppo negativo per vedere quali siti lo alimentano, poi recupera quelle pagine con Brand Mentions.
Entrambi gli endpoint lavorano sulle pagine web dei cinque tipi di sito indicati sopra. Per post e commenti sui social network, usa gli endpoint di piattaforma descritti nella guida all’API unificata per i social media. Per ciò che gli assistenti AI dicono del tuo brand, leggi la guida all’AI Search API.
Domande frequenti (FAQ)
Che cos’è un’API di brand monitoring?
Un’API che trova dove viene menzionato un brand, un prodotto o un argomento e con quale tono. La versione di SocQ restituisce le menzioni a livello di pagina con punteggi di sentiment, emozioni e autorevolezza, più una suddivisione aggregata per sentiment ed emozione.
Come cerco una frase esatta?
Racchiudila tra virgolette doppie dentro query, per esempio "\"notion ai\"" in JSON. La query può arrivare a 100 caratteri.
Quali tipi di siti sono coperti?
Le pagine sono classificate come news, blogs, message-boards, ecommerce o organization. Brand Mentions può essere limitato a uno di questi tipi con content_type.
Pago anche quando non viene trovato nulla?
Brand Mentions addebita il costo base di 10 crediti anche quando non viene trovata nessuna pagina, più 0.02 crediti per ogni pagina restituita. Brand Sentiment Analysis costa 10 crediti per richiesta.
Perché la mia attività di sentiment è ancora in esecuzione?
I termini molto generici con milioni di menzioni richiedono più tempo di analisi, fino a qualche minuto. Continua a interrogare lo stesso task_id; non inviarla di nuovo.
BRAND MONITORING API
Prova il flusso di lavoro con un URL pubblico di Brand Monitoring
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di Brand Monitoring