Monitoreo de marcaMenciones de marcaAnálisis de sentimientoReputaciónGuía de API

API de monitoreo de marca: menciones en la web con puntuaciones de sentimiento, emoción y autoridad

Dos nuevos endpoints de SocQ recopilan las páginas web que mencionan una marca con puntuaciones de sentimiento, emoción y autoridad, y reparten todas las menciones entre positivas, negativas y neutras.

SocQActualizado el 19 de noviembre de 20267 min de lectura

El monitoreo de marca suele empezar con dos preguntas: ¿dónde habla la web de nosotros y qué opina de nosotros? La primera requiere datos a nivel de página que pueda leer y distribuir. La segunda requiere un agregado que pueda graficar sin descargar millones de páginas.

El 2026-11-17 SocQ lanzó la plataforma Brand Monitoring con un endpoint para cada pregunta. Esta guía cubre qué devuelven, las solicitudes, el precio y cuándo usar cada uno.

Respuesta rápida: envíe una marca, producto o tema en query a POST /v1/brand-monitoring/mentions para obtener una lista de páginas web que lo mencionan, cada una con puntuaciones de sentimiento, emoción y autoridad. Envíe la misma query a POST /v1/brand-monitoring/sentiment para obtener una sola fila que reparte todas las menciones por sentimiento y emoción. Consulte GET /v1/tasks/{task_id} para ver los resultados.

Los nuevos endpoints de Brand Monitoring

1 crédito de SocQ = $0.005.

EndpointQué devuelvePrecio
Brand Mentions APIUna fila por cada página web que menciona la consulta: URL, título, el pasaje en torno a la mención, autor, idioma, país, tipo de sitio, puntuaciones de sentimiento y emoción, y autoridad de la página y del dominio10 créditos ($0.05) por solicitud + 0.02 créditos ($0.0001) por página
Brand Sentiment Analysis APIUna fila que agrupa todas las páginas que mencionan la consulta por sentimiento principal y por emoción más fuerte, con el número de páginas y los sitios, países, idiomas y tipos de sitio principales de cada grupo10 créditos ($0.05) por llamada

En Brand Mentions, la tarifa base de 10 créditos se aplica también cuando no se encuentra ninguna página.

Autenticación y flujo de tareas asíncronas

Todas las solicitudes a SocQ se autentican con una clave de API, y se usa el mismo encabezado para el envío, el estado de la tarea y las solicitudes de resultados:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Cada recopilación se ejecuta como una tarea en segundo plano:

submit -> task_id -> queued -> running -> succeeded
                                   \-> failed

La respuesta del envío contiene data.task_id y data.status. Consulte la tarea con ese ID:

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

Cuando status es succeeded, la respuesta incluye la primera página de registros normalizados en data.results.items. limit vale 50 por defecto y admite hasta 500; si has_more es verdadero, pase results.next_cursor como cursor para leer la página siguiente. Mientras una tarea está en queued, running o failed, el endpoint devuelve los metadatos de la tarea sin results.

Un callback_url opcional en el cuerpo del envío hace que SocQ envíe un POST con un resumen de la tarea cuando esta termina; lea los registros con GET /v1/tasks/{task_id}. Un tiempo de espera agotado en el cliente no cancela la tarea, así que retome con el mismo ID de tarea en lugar de pagar por un duplicado. 402 significa créditos insuficientes; 429 significa que la clave alcanzó un límite de solicitudes o de créditos.

Brand Mentions API: todas las páginas que lo mencionan

La Brand Mentions API devuelve páginas de toda la web que mencionan su consulta: reseñas en blogs, cobertura de prensa, hilos de foros y fichas de producto. Indique una marca, producto o tema en query, de hasta 100 caracteres. Ponga una frase entre comillas dobles para buscarla de forma exacta. content_type limita los resultados a sitios news, blogs, message-boards, ecommerce u organization. results_limit vale 100 por defecto y admite de 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
  }'

Cada fila describe una página:

  • Dónde: url, title, domain, language, country (dos letras; WW significa mundial) y page_types, como news, blogs o ecommerce.
  • Qué: text, el pasaje en torno a la mención, y author_name cuando se indica.
  • Qué tono tiene: sentiment con puntuaciones positive, negative y neutral de 0 a 1 que suman 1, y emotions con seis puntuaciones de 0 a 1: happiness, love, fun, share, sadness y anger.
  • Cuánto importa: content_quality_score (de 0 a 100), spam_score (de 0 a 100; cuanto más alto, más señales de spam), domain_rank y page_rank (de 0 a 1,000).
  • Cuándo: fetched_at, el momento en que se leyó la página por última vez.

Las puntuaciones de autoridad y de spam le permiten ordenar un conjunto grande de resultados para que el equipo lea primero las páginas de alta autoridad y poco spam, mientras que el reparto de sentimiento señala las páginas que requieren respuesta. 100 páginas cuestan 12 créditos ($0.06), y el máximo de 1,000 páginas cuesta 30 créditos ($0.15). Lista completa de campos: documentación de Brand Mentions.

Para seguir solo la prensa, añada un filtro:

{
  "query": "\"notion ai\"",
  "content_type": "news",
  "results_limit": 200
}

Brand Sentiment Analysis API: el desglose detrás de la cifra

La Brand Sentiment Analysis API responde a "¿qué opina la web de nosotros?" sin devolver páginas individuales. Las páginas que mencionan su consulta se agrupan por su sentimiento principal y, por separado, por su emoción más fuerte. Cada grupo indica cuántas páginas contiene y los sitios, países, idiomas y tipos de sitio que más aportan.

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"
  }'

La única fila del resultado tiene dos arrays:

  • sentiments: un grupo para cada uno de positive, negative y neutral.
  • emotions: un grupo para cada uno de happiness, love, fun, share, sadness y anger.

Cada grupo tiene un label, un mentions_count y top_domains, countries, languages y page_types, cada uno una lista de name y count, de mayor a menor. Esa estructura le permite saber si las críticas vienen de medios de comunicación o de un solo foro, y qué países las impulsan. Cada solicitud cuesta 10 créditos ($0.05). Los términos muy amplios, con millones de menciones, tardan más en analizarse, hasta unos minutos, así que consulte la tarea con paciencia. Consulte la documentación de Brand Sentiment Analysis.

Qué endpoint usar

  • Un panel semanal de reputación: ejecute Brand Sentiment Analysis para su marca y para cada competidor, guarde los recuentos y grafíquelos a lo largo del tiempo. Cuatro marcas cuestan 40 créditos ($0.20) por ejecución.
  • Una cola de triaje para el equipo de comunicación: ejecute Brand Mentions con content_type en news o message-boards y ordene por sentimiento negative y por domain_rank.
  • Investigar un pico: cuando los recuentos de sentimiento cambien, use los top_domains del grupo negativo para ver qué sitios lo impulsan y luego obtenga esas páginas con Brand Mentions.

Ambos endpoints trabajan con páginas web de los cinco tipos de sitio anteriores. Para publicaciones y comentarios en redes sociales, use los endpoints de cada plataforma descritos en la guía de la API unificada de redes sociales. Para saber qué dicen los asistentes de IA sobre su marca, consulte la guía de la AI Search API.

Preguntas frecuentes

¿Qué es una API de monitoreo de marca?

Una API que encuentra dónde se menciona una marca, producto o tema y qué tono tienen esas menciones. La versión de SocQ devuelve menciones a nivel de página con puntuaciones de sentimiento, emoción y autoridad, además de un desglose agregado por sentimiento y emoción.

¿Cómo busco una frase exacta?

Póngala entre comillas dobles dentro de query, por ejemplo "\"notion ai\"" en JSON. La consulta puede tener hasta 100 caracteres.

¿Qué tipos de sitios se cubren?

Las páginas se clasifican como news, blogs, message-boards, ecommerce u organization. Brand Mentions puede limitarse a uno de esos tipos con content_type.

¿Se me cobra si no se encuentra nada?

Brand Mentions cobra su tarifa base de 10 créditos incluso cuando no encuentra ninguna página, más 0.02 créditos por página devuelta. Brand Sentiment Analysis cuesta 10 créditos por solicitud.

¿Por qué mi tarea de sentimiento sigue en ejecución?

Los términos muy amplios, con millones de menciones, tardan más en analizarse, hasta unos minutos. Siga consultando el mismo task_id; no vuelva a enviarla.

BRAND MONITORING API

Probar el flujo de trabajo con una URL pública de Brand Monitoring

Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.

Ver las API de Brand Monitoring