Gráficos

POST /v1/charts convierte una pregunta con tus palabras en una tarjeta de gráfico que ya tomó las decisiones de visualización de datos: qué gráfico, qué medir, cómo agregarlo (totales, cuotas, agrupado por semana, media móvil, índice base 100), las cifras clave arriba, un título que cuenta el hallazgo («El dólar blue subió 4,1 % en la semana»), anotaciones y la fuente de cada valor. También puedes enviar tus propios datos y recibir la misma tarjeta.

• El gráfico que lo cuenta. Uno de 12 tipos, elegido para los datos. Si fuerzas otro, se respeta mientras los datos lo permitan.
• Cifras que puedes comprobar. Una cifra (un precio, una tasa, una encuesta) se encuentra tal cual en lo publicado y viene con las notas de donde salió. Nunca se inventa.
• Lista para publicar. Un iframe que se adapta a su ancho, una PNG al doble de resolución y un SVG, en cuatro temas, públicos por id. Desde la API, el servidor MCP o el playground del panel.
• Rápida. Una tarjeta se dibuja en menos de un milisegundo de nuestro lado. Los gráficos de cobertura vuelven en alrededor de un segundo; los de cifras, en 2 a 5 segundos.

Desde una consulta

curl https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: es" \
  -d '{ "query": "dólar blue esta semana" }'

Responde 201 con la tarjeta:

{
  "id": "chart_8k2m9q4x7w1p3n5z",
  "object": "chart",
  "type": "line",
  "theme": "light",
  "locale": "es",
  "chart": {
    "type": "line",
    "title": "El dólar blue subió 4,1 % en la semana",
    "subtitle": "Cotización de venta, en pesos · 19–25 sep",
    "x": { "kind": "time", "granularity": "day" },
    "y": { "format": "currency", "currency": "ARS", "label": "Venta" },
    "series": [
      {
        "name": "Venta",
        "points": [
          { "x": "2026-09-19", "y": 1215, "sources": [2] },
          { "x": "2026-09-24", "y": 1250, "sources": [1] },
          { "x": "2026-09-25", "y": 1265, "sources": [0, 1] }
        ]
      }
    ],
    "kpis": [
      { "label": "Último", "value": 1265, "change": { "value": 4.1, "percent": true } },
      { "label": "Máximo", "value": 1265 },
      { "label": "Mínimo", "value": 1215 }
    ]
  },
  "compatible_types": ["line", "area", "bar", "kpi", "table"],
  "plan": {
    "recipe": "figure_trend",
    "type": "line",
    "confidence": 1,
    "alternatives": [
      { "type": "area", "probability": 0.3 },
      { "type": "bar", "probability": 0.22 },
      { "type": "kpi", "probability": 0.14 }
    ],
    "topic": "el dólar blue",
    "needs": { "queries": ["dólar blue esta semana"], "mode": "fast", "days": 7, "min_points": 3, "max_results": 50 }
  },
  "sources": [
    {
      "url": "https://diario.example/economia/dolar-blue-hoy",
      "title": "El dólar blue cerró a 1.265 pesos",
      "source": "Diario Ejemplo",
      "published_at": "2026-09-25T18:10:00Z"
    },
    {
      "url": "https://noticias.example/mercados/cotizacion",
      "title": "Cotización del dólar: el blue tocó su máximo del mes",
      "source": "Noticias Ejemplo",
      "published_at": "2026-09-24T17:02:00Z"
    },
    {
      "url": "https://cronica.example/economia/blue-arranca-la-semana",
      "title": "El blue arranca la semana en 1.215 pesos",
      "source": "La Crónica Demo",
      "published_at": "2026-09-19T15:40:00Z"
    }
  ],
  "embed_url": "https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z",
  "image_url": "https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z.png",
  "svg_url": "https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z.svg",
  "svg": null,
  "created_at": "2026-09-26T14:02:11.482Z",
  "expires_at": "2026-12-25T14:02:11.482Z",
  "cached": false,
  "usage": { "cost_usd": 0.0019, "mode": "fast", "queries": 1, "duration_ms": 2840 },
  "warnings": []
}

• chart: lo que se dibuja. Las series, las cifras clave de arriba (kpis), las anotaciones, el formato de cada eje y un title que cuenta el hallazgo (salvo que envíes tu propio title).
• plan: qué se midió (recipe), el gráfico que eligió y alternatives: otros tipos que sirven, a los que puedes cambiar gratis con PATCH.
• compatible_types: todos los tipos que admiten estos datos.
• sources y los sources de cada punto: las notas detrás del gráfico, y los índices en sources donde se publicó cada valor.
• embed_url, image_url y svg_url: públicos por id, sin key. Mira Insertar en tu sitio y PNG y SVG.
• usage.cost_usd: lo que se cobró el pedido. Mira Precios.

Todo lo que conoces de la búsqueda también acota un gráfico: days, published_after, published_before, countries, languages, include_domains, exclude_domains y timezone. Si la consulta no nombra con «vs» lo que se compara, pásalo en compare (de 2 a 5).

Qué puedes pedir

El plan lee tu consulta y elige una receta: qué medir, el gráfico que lo cuenta, los días que mira y el modo más barato que consigue los datos (mode: "auto", el valor por defecto).

• Días. Los de la tabla valen salvo que una fecha en la consulta («esta semana», «en agosto»), days, published_after o published_before fijen el período.
• Modo. Envía mode para fijarlo. En auto, un gráfico de cifras que no encuentra suficientes en los titulares y las bajadas lee las mejores notas (normal), y se cobra en ese modo.
• Primero, las palabras. Cuando la consulta lo dice («cobertura», «tono», «qué medios», «cronología», «precio», «vs»), el plan sigue a las palabras (plan.confidence: 1). Si no, se decide una vez y se recuerda 7 días.
• Índice propio. Con index (idx_…), el gráfico sale de los datos estructurados que declara cada página de tu índice propio: precio, puntuación, reseñas, disponibilidad, marca.

Una pregunta tipada arma un gráfico answers: cómo la responden las notas. Una pregunta por gráfico, con el mismo formato que en la salida estructurada:

{
  "query": "el Presupuesto 2027",
  "questions": {
    "postura": {
      "type": "choice",
      "instructions": "¿Qué postura toma la nota sobre el Presupuesto?",
      "criteria": { "a_favor": null, "critica": null, "neutral": "Informa sin tomar partido." }
    }
  }
}

Cómo se encuentran las cifras

Un gráfico con cifras (figure_trend, figure_compare) nunca inventa un número:

• Tal cual. Los números se encuentran como están escritos en los titulares, las bajadas y los fragmentos de las notas, con su moneda o su unidad. Después, cada uno sólo se confirma, o se descarta, como el valor que pediste.
• Un valor por día. Cada punto es la mediana de lo publicado ese día, así dos medios con cifras apenas distintas no dibujan un zigzag. En una comparación, cada nombre lleva su último valor publicado.
• Una fuente para cada punto. Los sources de cada punto son índices en los sources de la respuesta: las notas donde se publicó ese valor. Muéstralas en un tooltip o en una nota al pie.

{ "x": "2026-09-25", "y": 1265, "sources": [0, 1] }

Si un medio pide después que no lo mostremos, sus fuentes salen de la tarjeta cuando se sirve, y un punto que se queda sin fuente se oculta.

Desde tus datos

Envía data en lugar de query y recibes la misma tarjeta: elegimos el gráfico (con type: "auto"), ordenamos, resumimos, agregamos las cifras clave y escribimos un título (salvo que envíes title). Cuesta $0,30 cada 1.000 gráficos. source fija la línea del pie.

Series

curl https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: es" \
  -d '{
    "data": {
      "series": [
        {
          "name": "Suscriptores",
          "points": [
            { "x": "2026-06-01", "y": 18200 },
            { "x": "2026-07-01", "y": 19650 },
            { "x": "2026-08-01", "y": 21400 },
            { "x": "2026-09-01", "y": 23900 }
          ]
        }
      ],
      "y": { "label": "Suscriptores", "format": "number" }
    },
    "source": "Diario Ejemplo, datos internos"
  }'

• x es una fecha (2026-09-01) para un eje de tiempo, un número para uno numérico (una dispersión) o un texto para categorías. Para decirlo tú, usa data.x.kind: time, category o number.
• data.y da formato a los valores: format (number, percent o currency, con currency: "USD"), unit, decimals, label, y higher_is_better: false cuando menos es mejor (un precio): los rankings ponen entonces lo más bajo primero.
• En una dispersión, data.x_measure da formato al eje x, el r de cada punto fija su tamaño y label le pone nombre.
• role en una serie (positive, neutral, negative, other) la pinta como un tono. highlight nombra la categoría que se destaca.

Eventos

Una lista de hechos con fecha arma una cronología:

{
  "data": {
    "events": [
      { "date": "2026-07-30", "label": "El informe técnico sobre las filtraciones de la represa", "detail": "Diario Ejemplo" },
      { "date": "2026-08-06", "label": "La provincia frena la obra" },
      { "date": "2026-08-19", "label": "La constructora presenta un amparo", "end": "2026-08-22" }
    ]
  },
  "title": "El caso de la represa, en tres hitos"
}

Columnas y filas

{
  "data": {
    "columns": [
      { "key": "modelo", "label": "Modelo" },
      { "key": "precio", "label": "Precio", "format": { "format": "currency", "currency": "USD" } },
      { "key": "puntuacion", "label": "Puntuación", "format": { "decimals": 1 } }
    ],
    "rows": [
      { "modelo": "Ridgeline Trail 4", "precio": 109, "puntuacion": 4.6 },
      { "modelo": "Canyon Grip GTX", "precio": 119, "puntuacion": 4.4 }
    ]
  }
}

Con type: "auto", los eventos arman una timeline; las columnas y filas, una table; un x numérico, un scatter; las fechas, una line (un kpi si son uno o dos puntos); varias series de categorías, un stacked_bar; porcentajes que suman 100 en hasta 6 partes, un donut; más de 7 categorías, un bar_horizontal; menos, un bar.

Tipos de gráfico

type: "auto" (el valor por defecto) elige el que mejor cuenta los datos. Los otros 12:

Forzar un tipo ("type": "donut") funciona mientras los datos lo permitan. Si no, la tarjeta se dibuja con el tipo más cercano que sí sirve y lo dice en warnings con chart_type_adjusted. compatible_types lista los tipos que admiten estos datos, del mejor al aceptable.

Las reglas que aplicamos

Lo que haría alguien que vive de hacer gráficos, aplicado a cada tarjeta. Los mismos datos dan siempre la misma tarjeta.

• Las series diarias largas pasan a semanas (más de 45 días) o a meses (más de 8 meses), sumando los conteos y quedándose con el último valor de una cifra (grouped).
• Nada de doble eje. Las líneas de escalas muy distintas (más de 25 veces) se comparan como índice, base 100 (indexed).
• Las series diarias ruidosas de tres semanas o más llevan una media móvil de 7 puntos, con la serie cruda tenue debajo (chart.smoothing).
• Las tortas y las donas muestran como mucho 6 porciones, con el resto en «Otros», siempre al final. Los rankings muestran como mucho 12 barras; las líneas, las áreas y las barras apiladas, hasta 6 series.
• Los rankings van de mayor a menor, o de menor a mayor cuando bajar es mejor: un precio, la inflación, el riesgo país.
• Con nombres largos, las barras verticales pasan a un ranking horizontal, para que entre cada etiqueta.
• Escala logarítmica sólo en líneas, y sólo cuando los valores abarcan más de 200 veces. Nunca en barras.
• Las cifras clave arriba: total, pico y promedio diario en la cobertura; último (con su variación), máximo y mínimo en una cifra.
• El título cuenta el hallazgo: «La cobertura del Presupuesto tuvo su pico el 10 sep», «Milei concentra el 42 % de la cobertura», «Los modelos más caros no son los mejor puntuados».

Temas

La primera serie es siempre el azul eléctrico de typesearch, y las demás se distinguen también con daltonismo. Fija theme al crear el gráfico, cámbialo gratis con PATCH, o muestra una vista con otro tema con ?theme= en el embed o en la imagen.

Insertar en tu sitio

embed_url es una página hecha para ir dentro de un iframe. Se adapta a su ancho (por debajo de 480 px pasa a una versión compacta), muestra tooltips con el mouse y al tocar, pesa pocos KB y no carga nada de terceros: las fuentes son nuestras.

<iframe
  src="https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z"
  title="El dólar blue subió 4,1 % en la semana"
  style="width: 100%; border: 0"
  height="440"
  loading="lazy"
></iframe>

La página le avisa a la tuya el alto que necesita, al cargar y cada vez que cambia de tamaño, con { type: "typesearch:chart:resize", id, height }. Escúchalo una vez y cada gráfico de la página entra sin barras de desplazamiento:

<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://api.typesearch.ai') return;
    const data = event.data;
    if (!data || data.type !== 'typesearch:chart:resize') return;
    for (const frame of document.querySelectorAll('iframe')) {
      if (frame.contentWindow === event.source) frame.style.height = `${data.height}px`;
    }
  });
</script>

data.id es el id del gráfico, si prefieres reconocerlo por ahí. Agrega ?theme=dark (o editorial, electric) para mostrarlo con otro tema sin crear otro gráfico.

Los embeds, las imágenes y los SVG se guardan en caché 5 minutos: un cambio hecho con PATCH se ve dentro de ese plazo. Cada IP puede cargar hasta 600 por minuto.

PNG y SVG

• image_url (….png): la tarjeta al doble de resolución, para chat, email o presentaciones. En Markdown: ![El dólar blue subió 4,1 % en la semana](https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z.png).
• svg_url (….svg): la tarjeta en vectores.
• ?size=compact da cualquiera de las dos en la versión angosta, para celulares e historias, y ?theme=, con otro tema: https://api.typesearch.ai/embed/chart_8k2m9q4x7w1p3n5z.png?size=compact&theme=electric.

Cambiar un gráfico

PATCH /v1/charts/{id} cambia el type, el theme, el title, el subtitle o el locale (en o es). Vuelve a dibujar con los mismos datos, sin buscar de nuevo, y es gratis. Elige el tipo de compatible_types. Sin un título tuyo, el título se vuelve a escribir para el nuevo tipo y el nuevo idioma.

curl -X PATCH https://api.typesearch.ai/v1/charts/chart_8k2m9q4x7w1p3n5z \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "area", "theme": "editorial" }'

Responde con el gráfico actualizado. embed_url, image_url y svg_url no cambian.

Listar, ver y borrar

• GET /v1/charts: tus gráficos, del más nuevo al más viejo, de a limit (hasta 100). Si has_more es true, pasa next_before como before para la página siguiente.
• GET /v1/charts/{id}: un gráfico, con sus datos, su plan y sus fuentes.
• DELETE /v1/charts/{id}: lo borra ({ "id": "chart_…", "object": "chart", "deleted": true }). Su embed, su imagen y su SVG dejan de funcionar.

Todas las keys de tu organización ven los mismos gráficos. Los gráficos guardados vencen a los 90 días con pago por uso y nunca con el plan mensual de créditos: expires_at dice cuándo, o null. Mira la referencia.

Mira el plan primero

plan_only: true devuelve sólo el plan: la receta, el tipo de gráfico, sus alternativas y lo que buscaría (plan.needs: consultas, modo, días, puntos mínimos). No busca ni dibuja, y es gratis. chart e id vuelven en null.

Sin guardarlo

store: false no guarda nada: no hay id ni direcciones, y el SVG viene en la respuesta, en svg. Cuesta lo mismo. Para recibir el SVG también con un gráfico guardado, agrega include_svg: true.

Errores y avisos

insufficient_data dice cuántos puntos necesitaba y cuántos encontró. Prueba con más días, otro modo o una consulta más amplia:

{
  "type": "urn:typesearch:error:insufficient_data",
  "status": 422,
  "code": "insufficient_data",
  "detail": "Not enough data for this chart: it needs 3 and found 1. Try more days, another mode or a broader query. Not billed.",
  "request_id": "req_Vt4mQ8zK1pXa"
}

Los avisos no detienen el gráfico. Vienen en warnings, cada uno con un code y un message:

Precios

Un gráfico desde una consulta cuesta su búsqueda, en el modo que necesitó y por consulta, más $0,50 cada 1.000 gráficos. Con una consulta:

Un gráfico que compara nombres busca una consulta por nombre: la cuota de voz entre tres nombres en ultra cuesta tres búsquedas a $1,00 cada 1.000, más un adicional. Desde tus datos, un gráfico cuesta $0,30 cada 1.000. usage.cost_usd dice cuánto costó cada uno.

Gratis:

• Cada vista de un embed, una imagen o un SVG.
• GET, listar, PATCH y DELETE.
• El mismo pedido dentro de 10 minutos: vuelve el mismo gráfico con cached: true. Si sólo la búsqueda salió de la caché, pagas sólo el adicional.
• Los errores, también 422 insufficient_data.
• plan_only.

La lista está en el documento OpenAPI, en x-pricing.per_1000_charts: { "query_addon": 0.5, "from_data": 0.3 }. Como referencia, la Search de Tako, que devuelve tarjetas de gráficos, cuesta $7 cada 1.000. Mira Costos y caché.

Desde el servidor MCP

La herramienta create_chart del servidor MCP arma la misma tarjeta desde una consulta, así un agente puede responder con un gráfico:

{ "query": "cobertura de Milei vs Bullrich vs Kicillof", "theme": "dark" }

Recibe query, type, theme, days, compare, countries, languages e index, y devuelve el title, el subtitle, image_url (para mostrar), embed_url, key_figures, los valores dibujados en data, events, sources y cost_usd. La misma key, los mismos precios.