Brand monitoringMenzioni del brandAnalisi del sentimentReputazioneGuida alle API

Brand Monitoring API: menzioni sul web con punteggi di sentiment, emozioni e autorevolezza

Due nuovi endpoint SocQ raccolgono le pagine web che menzionano un brand con punteggi di sentiment, emozioni e autorevolezza, e suddividono tutte le menzioni in positive, negative e neutre.

SocQAggiornato il 19 novembre 20267 min di lettura

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 query a POST /v1/brand-monitoring/mentions per ottenere un elenco di pagine web che lo menzionano, ognuna con punteggi di sentiment, emozioni e autorevolezza. Invia la stessa query a POST /v1/brand-monitoring/sentiment per ottenere una riga che suddivide tutte le menzioni per sentiment ed emozione. Interroga GET /v1/tasks/{task_id} per i risultati.

I nuovi endpoint di Brand Monitoring

1 credito SocQ = $0.005.

EndpointCosa restituiscePrezzo
Brand Mentions APIUna 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 dominio10 crediti ($0.05) per richiesta + 0.02 crediti ($0.0001) per pagina
Brand Sentiment Analysis APIUna 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 gruppo10 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; WW significa mondo intero) e page_types, per esempio news, blogs o ecommerce.
  • Cosa: text, il passaggio attorno alla menzione, e author_name quando indicato.
  • Con quale tono: sentiment con punteggi positive, negative e neutral da 0 a 1 che sommati danno 1, ed emotions con sei punteggi da 0 a 1: happiness, love, fun, share, sadness e anger.
  • Quanto conta: content_quality_score (da 0 a 100), spam_score (da 0 a 100, più è alto più segnali di spam ci sono), domain_rank e page_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 per positive, negative e neutral.
  • emotions: un gruppo ciascuno per happiness, love, fun, share, sadness e anger.

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_type impostato su news o message-boards, poi ordina per sentiment negative e per domain_rank.
  • Indagare un picco: quando i conteggi del sentiment cambiano, usa i top_domains del 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