La API de Social Listening de Vídeo

01 Visión general

La YBOT Partner Data API sirve el dataset propio de social listening de vídeo de YBOT — las menciones de marca y producto que YBOT detecta y analiza en vídeo disponible públicamente en YouTube, TikTok e Instagram — como un pequeño conjunto de operaciones JSON de solo lectura. Recibes los insights derivados de YBOT, no los datos de las plataformas. Tus propios sistemas, o un agente de IA que use las operaciones como tools, la llaman directamente; nadie tiene que abrir un dashboard.

Todo vive bajo /v1, acepta y devuelve JSON, y está protegido por una API key con el scope data:search. La salida está siempre agregada y filtrada por lista de permitidos: los datos personales — nombres, citas literales, fechas de nacimiento — nunca se devuelven.

02 Inicio rápido

Tres pasos hasta tu primer resultado de cuota de voz competitiva.

curl -X POST https://partners.yourbrandontime.com/v1/sector \
  -H "X-API-Key: pk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "brands": [ {"label":"Repsol","terms":["Repsol"]},
                {"label":"Iberdrola","terms":["Iberdrola"]} ],
       "from_date":"2026-01-01", "to_date":"2026-06-30" }'

03 Autenticación

Envía tu key en la cabecera X-API-Key en cada petición. Las keys llevan un scope y un plan; el plan fija un límite de peticiones por ventana fija y una cuota mensual de peticiones. Una key ausente o sin el scope adecuado se rechaza antes de ejecutar ninguna consulta.

curl https://partners.yourbrandontime.com/v1/schema \
  -H "X-API-Key: pk_live_your_key_here"

Algunas keys son access_level: "raw" (conjuntos de resultados de search más grandes); la mayoría son aggregate (ejemplos con tope de 10).

04 Modelo de datos

Tres índices respaldan todas las operaciones. Filtras, agrupas y clasificas sobre sus campos declarados; una consulta que nombre un campo fuera de la lista de permitidos se rechaza. La salida es siempre un subconjunto depurado.

Tipos de filtro: term (exacto), range (numérico {gte,lte}), date_range (fechas ISO {gte,lte}). Las métricas combinan un tipo — count · sum · avg · min · max — con un campo de métrica.

05 aggregate

La primitiva central para «preguntas abiertas»: agrupa un índice por una dimensión y clasifica los buckets por una métrica. «¿Qué creadores hablan más de retinol?» → agrupa siv_business_ideas por channel_name, filtra components: "retinol", cuenta.

curl -X POST https://partners.yourbrandontime.com/v1/aggregate \
  -H "X-API-Key: pk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "index":"siv_business_ideas", "group_by":"channel_name",
       "filters":{ "components":"retinol" },
       "metric":{ "type":"avg", "field":"sentiment_score" }, "size":10 }'

→ { "matched_documents":1284, "buckets":[
     { "key":"Hyram", "count":61, "metric":0.42, "metric_type":"avg:sentiment_score" } ] }

06 search

Documentos de ejemplo — solo campos de la lista de permitidos, con tope de 10 salvo que tu key sea access_level: "raw". q es búsqueda de texto completo sobre los campos de texto libre del índice (p. ej. título/descripción de siv_info).

07 creators

Un wrapper de conveniencia sobre search en siv_content_creator: creadores clasificados con demografía de audiencia agregada. Filtra por nicho, geografía o tamaño; ordena por cualquier métrica de creador.

Devuelve perfiles de creador con subscriber_count, engagement_rate_viewers y las distribuciones agregadas viewer_age_distribution / viewer_gender_distribution / viewer_country_distribution.

08 co-mentions

Encuentra vídeos o canales que mencionan todas las marcas indicadas juntas — la primitiva de co-ocurrencia detrás de «quién habla de A y de B». Devuelve solo IDs + recuentos (una agregación), nunca documentos en bruto.

curl -X POST https://partners.yourbrandontime.com/v1/co-mentions \
  -H "X-API-Key: pk_live_your_key_here" -H "Content-Type: application/json" \
  -d '{ "values":["Nike","IKEA"], "group_by":"video_id" }'

→ { "results":[ { "key":"vid_88", "total_mentions":7, "matched_values":2 } ] }

09 sector · Share of Voice

Clasifica un conjunto competitivo de marcas según la presencia de cada una en vídeo frente al resto, mes a mes — volumen, alcance, sentimiento y temas. Este es el endpoint detrás del informe sectorial de Share of Voice (cuota de voz).

{ "brands":[ {
    "label":"Repsol", "coverage":"ok", "low_confidence":false,
    "totals":{ "unique_videos":760, "views":26900000 },
    "series":[ { "month":"2026-01",
      "unique_videos":152,   // 1 por vídeo
      "mentions":158,        // cada mención (100 en un vídeo = 100)
      "views":8673694, "sentiment":0.061,
      "volume_sov":76.38,     // % de cuota por vídeos únicos
      "reach_sov":97.27,      // % de cuota por views
      "top_topics":[ { "topic":"energy", "count":50 } ] } ] } ],
  "meta":{ "from":"2026-01-01", "to":"2026-06-30",
    "caps":{ "max_brands":30, "video_cap":3000, "low_coverage":20 } } }

10 schema

Una descripción legible por máquina de cada operación, los índices consultables, sus campos y valores permitidos — la API se autodocumenta en tiempo de ejecución y un agente puede usar las operaciones como tools sin codificar el contrato a mano.

11 Uso de la API desde un agente de IA

La API es deliberadamente amigable para agentes: un puñado de operaciones tipadas y de solo lectura con guardarraíles estrictos y un contrato legible por máquina. El cableado previsto — el mismo patrón que usa el DAI de Epsilon — es:

{
  "name": "sector_share_of_voice",
  "description": "Rank a set of brands by share of voice in video (volume, reach, sentiment, topics) over a date window.",
  "input_schema": {
    "type": "object",
    "properties": {
      "brands": { "type": "array", "maxItems": 30,
        "items": { "type": "object", "required": ["label","terms"] } },
      "from_date": { "type": "string", "format": "date" },
      "to_date":   { "type": "string", "format": "date" }
    },
    "required": ["brands","from_date","to_date"]
  }
}  // handler del tool = POST /v1/sector con el input del tool como cuerpo JSON

12 Recetas

Preguntas habituales y la llamada que responde a cada una.

13 Glosario

Share of Voice (SoV)

La presencia de una marca como porcentaje del conjunto monitorizado durante un periodo — su «cuota de voz». Se reporta de dos formas: por volumen y por alcance.

SoV por volumen

Cuota medida por vídeos únicos — cada vídeo cuenta una vez, aparezca la marca las veces que aparezca.

SoV por alcance

Cuota medida por views — pondera cada mención por cuántas personas han podido verla.

Mención vs. vídeo único

Una mention cuenta cada aparición (100 en un vídeo = 100); un unique_video cuenta el vídeo una sola vez.

Puntuación de sentimiento

Tono medio de las menciones, de −1 (negativo) a +1 (positivo).

Co-mención

Dos o más marcas apareciendo juntas en el mismo vídeo o canal — una señal de comparación, colaboración o encuadre competitivo.

Coverage (cobertura)

low cuando una marca tiene demasiado pocos vídeos para que sus porcentajes sean estadísticamente fiables.

Tema (topic)

Un tema extraído por LLM y asociado a una mención (p. ej. energy, oil-and-gas), con un recuento de frecuencia.

14 Preguntas frecuentes

15 Errores

Los errores son JSON con un message legible. Las violaciones de guardarraíl nombran el campo exacto que hay que corregir.

16 Límites y cuota

Los datos se calculan y almacenan en la UE (Scaleway) — sin nube estadounidense en el camino. La API devuelve únicamente agregados y campos de la lista de permitidos; los datos personales en bruto nunca salen.