Crear un gráfico

Una tarjeta de gráfico desde una consulta con tus palabras, o desde tus propios datos.

POSThttps://api.typesearch.ai/v1/charts

Planea qué medir, lo busca y dibuja una tarjeta con las cifras clave, un título que cuenta el hallazgo, anotaciones y la fuente de cada valor. O envía data (series, eventos, o columnas y filas) y recibe la misma tarjeta con tus propios números. Envía query o data, no los dos. La guía de gráficos explica cada receta, tipo y regla.

Responde 201 Created con un gráfico nuevo, y 200 OK con plan_only, con store: false o cuando el mismo pedido dentro de 10 minutos devuelve el mismo gráfico (cached: true, no se cobra). Cuando la búsqueda no encuentra datos suficientes responde 422 insufficient_data, sin cobrar.

Desde una consulta cuesta su búsqueda (el modo que necesitó, por consulta) más $0,50 cada 1.000 gráficos; desde tus datos, $0,30 cada 1.000. Mira los precios.

Cuerpo

querystring
Lo que quieres ver, con tus palabras y en cualquier idioma: «dólar blue esta semana», «cobertura de Milei vs Bullrich», «qué medios publican sobre el litio», o «precios» con index. De 2 a 200 caracteres. Envía query o data, no los dos.
dataobject
Tus propios datos en lugar de una consulta, sin búsqueda: series de puntos, events para una cronología, o columns y rows para una tabla, más formatos opcionales para los ejes (x, y, x_measure) y un highlight.
Series de puntos, eventos, o columnas y filas. Mira Desde tus datos en la guía de gráficos.
typeenum<string>Por defecto: "auto"
El tipo de gráfico. auto elige el que mejor cuenta los datos. Cualquier otro se respeta mientras los datos lo permitan; si no, se dibuja el tipo más cercano que sí sirve, con un aviso chart_type_adjusted.
Uno de: auto · line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
indexstring
Arma el gráfico con tu índice propio (idx_…) en lugar de las noticias: precios, precio frente a puntuación, disponibilidad o marcas, con los datos que declara cada página. Sin filtro de fechas salvo que pongas uno.
modeenum<string>Por defecto: "auto"
auto usa el modo más barato que consigue los datos: ultra para la cobertura, la cuota de voz y los medios, fast para lo demás, y normal cuando las cifras no están en los titulares y las bajadas. O fíjalo en ultra, fast, normal o deep. El gráfico se cobra en el modo en que termina.
comparestring[]
Lo que se compara, de 2 a 5 nombres, si la consulta no lo dice con «vs». Cada nombre se busca, y se cobra, como una consulta.
Elementos: hasta 5
questionsmapa<string, …>
Una pregunta tipada (boolean, choice o score), con el mismo formato que en la búsqueda: el gráfico muestra cómo se reparten las respuestas entre las notas.
daysinteger | null
Los últimos N días, de 1 a 365. Por defecto depende de la receta: 30 para la cobertura, 7 para las cifras, todo el índice con index (mira la guía de gráficos). Una fecha en la consulta, published_after o published_before fijan el período en su lugar.
Rango: 1–365
published_afterdate | date-time
Publicadas desde este momento. Una fecha sola (2026-09-20) cubre el día entero en UTC−3; una fecha y hora necesita la zona.
published_beforedate | date-time
Publicadas hasta este momento, inclusive. El mismo formato que published_after.
countriesstring[]
Sólo fuentes con sede en estos países: códigos ISO 3166-1 alfa-2, como AR o US.
Elementos: hasta 50
languagesstring[]
Sólo fuentes que publican en estos idiomas: códigos ISO 639-1, como es o en. Una etiqueta como pt-BR cuenta como pt.
Elementos: hasta 20
include_domainsstring[]
Sólo estos dominios o rutas, hasta 20. Un dominio incluye sus subdominios.
Elementos: hasta 20
exclude_domainsstring[]
Nunca estos dominios o rutas, hasta 20.
Elementos: hasta 20
timezonestring
La zona horaria IANA que decide qué día es «hoy» y dónde empieza cada día, como America/Mexico_City. Por defecto, America/Argentina/Buenos_Aires.
titlestring
Tu título. Sin uno, el gráfico lleva un título que cuenta el hallazgo.
subtitlestring
Tu bajada. Sin una, un gráfico desde una consulta dice qué se midió y en qué período.
sourcestring
La línea de la fuente en el pie, para tus propios datos.
themeenum<string>Por defecto: "light"
light (el valor por defecto), dark, editorial (papel cálido, para medios) o electric (azul profundo, para presentaciones). Cámbialo después con PATCH, o en cada vista con ?theme=.
localeenum<string>
El idioma de los títulos, las etiquetas y los números: en o es. Por defecto, el del encabezado Accept-Language.
plan_onlybooleanPor defecto: false
Devuelve sólo el plan (qué se mediría, el tipo de gráfico y los datos que necesita), sin buscar ni dibujar. Gratis.
storebooleanPor defecto: true
false no guarda nada: no hay id ni direcciones, y el SVG viene en svg. Cuesta lo mismo.
include_svgbooleanPor defecto: false
Devuelve también el SVG en svg con un gráfico guardado.

Respuesta

idstring | null
El id del gráfico, chart_…. null con store: false o plan_only.
object"chart"
Siempre chart.
typeenum<string> | null
El tipo de gráfico que se dibujó. null con plan_only.
Uno de: line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
themeenum<string>
El tema con que se dibuja.
Uno de: light · dark · editorial · electric
localeenum<string>
El idioma de los títulos, las etiquetas y los números.
Uno de: en · es
chartobject | null
Lo que se dibuja: las series y sus puntos, las cifras clave de arriba, las anotaciones, los eventos o las filas, y un title que cuenta el hallazgo. null con plan_only.
Las series (series[].points[] con x, y y sources), kpis, annotations, events, columns y rows, y el formato de cada eje (x, y, x_measure).
compatible_typesenum<string>[]
Todos los tipos de gráfico que admiten estos datos, del mejor al aceptable. Cambia entre ellos gratis con PATCH.
Uno de: line · area · bar · bar_horizontal · stacked_bar · pie · donut · scatter · funnel · timeline · kpi · table
planobject | null
Desde una consulta: qué se midió (recipe), por qué este gráfico, otros tipos que sirven y los datos que necesitó. null con tus propios datos.
La receta (recipe), el tipo (type), alternatives (con su probability), topic, entities y needs (queries, mode, days, min_points, max_results).
sourcesobject[]
Las notas detrás del gráfico. Los sources de cada punto son índices en esta lista. Vacía con tus propios datos.
Ver los campos
- urlstring
  La URL de la nota.
- titlestring
  Su titular.
- sourcestring | null
  El nombre del medio.
- published_atstring | null
  Cuándo se publicó.
embed_urlstring | null
Una página para un iframe: se adapta a su ancho y muestra tooltips. Pública, sin key. Agrega ?theme= para otro tema. null si no se guarda nada.
image_urlstring | null
La PNG al doble de resolución, para chat, email o presentaciones. Agrega ?size=compact para la versión angosta.
svg_urlstring | null
El SVG. Agrega ?size=compact para la versión angosta.
svgstring | null
El SVG mismo, con include_svg o store: false. Si no, null.
created_atstring | null
Cuándo se creó.
expires_atstring | null
Cuándo vence: a los 90 días de creado con pago por uso. null con el plan mensual de créditos, donde nunca vence.
cachedboolean
true si el mismo pedido de los últimos 10 minutos devolvió el mismo gráfico. No se cobra.
usageobject
Lo que costó el pedido.
Ver los campos
- cost_usdnumber
  Costo en dólares: la búsqueda en su modo, por consulta, más el adicional del gráfico; o el precio de un gráfico con tus datos. 0 si salió de la caché, y en GET y PATCH.
- modeenum<string> | null
  El modo en que se cobró, o data para tus propios datos. null si no se cobró nada.
  Uno de: ultra · fast · normal · deep · data
- queriesinteger
  Cuántas consultas se buscaron: una por nombre en una comparación.
  Rango: -9007199254740991–9007199254740991
- duration_msinteger
  Tiempo en el servidor, en milisegundos.
  Rango: -9007199254740991–9007199254740991
warningsobject[]
Avisos que no detuvieron el gráfico: chart_type_adjusted, grouped o indexed.
Ver los campos
- codestring
  Un código estable.
- messagestring
  Una explicación para personas.

curl https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: es" \
  -d '{
    "query": "qué medios publican sobre el litio",
    "theme": "editorial"
  }'

201 Created (resumida)

{
  "id": "chart_3v7n1q8m2k5x9w4p",
  "object": "chart",
  "type": "bar_horizontal",
  "theme": "editorial",
  "locale": "es",
  "chart": {
    "type": "bar_horizontal",
    "title": "Diario Ejemplo es el que más publicó sobre el litio",
    "subtitle": "Notas que mencionan el litio, por medio · 28 ago–26 sep",
    "x": { "kind": "category" },
    "y": { "format": "number", "label": "notas" },
    "part_of_whole": true,
    "series": [
      {
        "name": "Notas",
        "points": [
          { "x": "Diario Ejemplo", "y": 42 },
          { "x": "Noticias Ejemplo", "y": 31 },
          { "x": "La Crónica Demo", "y": 27 }
        ]
      }
    ]
  },
  "compatible_types": ["bar", "bar_horizontal", "donut", "pie", "kpi", "table"],
  "plan": {
    "recipe": "outlets",
    "measure": "outlets",
    "x_axis": "outlet",
    "type": "bar_horizontal",
    "part_of_whole": true,
    "confidence": 1,
    "alternatives": [
      { "type": "bar", "probability": 0 },
      { "type": "donut", "probability": 0 },
      { "type": "pie", "probability": 0 }
    ],
    "topic": "el litio",
    "entities": [],
    "needs": { "queries": ["el litio"], "mode": "ultra", "days": 30, "min_points": 1, "max_results": 10 }
  },
  "sources": [
    {
      "url": "https://diario.example/economia/litio-exportaciones",
      "title": "Las exportaciones de litio marcaron un récord en agosto",
      "source": "Diario Ejemplo",
      "published_at": "2026-09-25T11:20:00Z"
    }
  ],
  "embed_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p",
  "image_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p.png",
  "svg_url": "https://api.typesearch.ai/embed/chart_3v7n1q8m2k5x9w4p.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.0015, "mode": "ultra", "queries": 1, "duration_ms": 910 },
  "warnings": []
}

Cuerpo: tus propios datos

{
  "data": {
    "series": [
      {
        "name": "Cuota",
        "points": [
          { "x": "Buscadores", "y": 46 },
          { "x": "Redes", "y": 31 },
          { "x": "Directo", "y": 23 }
        ]
      }
    ],
    "y": { "format": "percent" }
  },
  "title": "De dónde llegan nuestros lectores",
  "source": "Analítica de Diario Ejemplo"
}