Create a chart card from a query or your own data

Ask in plain words («blue dollar this week», «standings last Formula 1 race», «elections in Brazil», «Milei vs Bullrich coverage», «news in The Guardian this week», «prices in my catalog» with index). It first works out what you expect to see (interpretation, with other readings you can ask for), then gets that data: the finishing positions of the latest race, poll or result shares, wins in the season, coverage, tone, outlets, a timeline or the figures the articles publish, verified against the sources. It never fails while there are articles on the topic: if the exact data is not published or takes too long, it shows the closest thing (rung: exact, partial, related, coverage, stories) with a warning, and a stored chart keeps improving until the exact data arrives. With stream: true, server-sent events: step, result and improved. Or send data (series, events, or columns and rows) and it picks the chart, sorts, summarizes and titles it. type forces one of 12 types while the data allows. From a query it costs its search (the mode it ended in, one per compared name; free if cached) plus the chart add-on; from your data, the data price (see x-pricing, per_1000_charts). The same request within 10 minutes returns the same card, free. No articles at all: 422 insufficient_data, not billed.

post/v1/charts

Request

  • Base URL: https://api.typesearch.ai
  • URL: https://api.typesearch.ai/v1/charts
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

querystring

What you want to see, in plain words: «blue dollar this week», «Milei vs Bullrich coverage», «prices in my catalog».

type'auto' | 'line' | 'area' | 'bar' | 'bar_horizontal' | 'stacked_bar' | 'pie' | 'donut' | 'scatter' | 'funnel' | 'timeline' | 'kpi' | 'table'

The chart type. auto (the default) picks the one that tells the data best; any other forces it while the data allows.

indexstring

Build the chart from your custom index (idx_…) instead of the news: prices, ratings, availability and brands.

mode'auto' | 'ultra' | 'fast' | 'normal' | 'deep'

auto: the cheapest mode that gets the data (coverage in ultra, figures in fast, reading articles only if needed). Or fix it.

comparestring[]

What to compare (2 to 5), if the query does not say it with «vs».

questionsobject

One typed question (boolean, choice, score): the chart shows how the answers split across the articles.

daysinteger nullable

The last N days. By default it depends on what is measured: 30 for coverage, share of voice and outlets, 14 for tone, 60 for a timeline, 7 for figures.

countriesstring[]

Only sources from these countries: ISO 3166-1 alpha-2 codes, such as AR or US.

languagesstring[]

Only sources that publish in these languages: ISO 639-1 codes, such as es or en (a BCP 47 tag such as pt-BR counts as pt).

include_domainsstring[]

Only these domains or paths. A domain includes its subdomains.

exclude_domainsstring[]

Never these domains or paths.

timezonestring

IANA time zone that decides what day «today» is. Defaults to Argentina (America/Argentina/Buenos_Aires).

titlestring

Your title. Without one, the chart gets a title that states the finding.

subtitlestring
sourcestring

The source line in the footer, for your own data.

theme'light' | 'dark' | 'editorial' | 'electric'

light, dark, editorial (warm paper, for media) or electric (deep blue, for presentations).

locale'en' | 'es'

Language of titles, labels and numbers. Defaults to Accept-Language.

interpretationstring

One of interpretation.alternatives from a previous response: chart that reading of the query instead.

plan_onlyboolean

Only the plan: what we understood, what would be measured, the chart type and the data needed. Free, without searching.

streamboolean

Server-sent events: step while it works, result with the chart and, if a better chart arrives after the deadline, improved.

storeboolean

false: nothing is stored (no embed_url); the SVG comes in the response.

include_svgboolean

Include the SVG in the response.

Response

With plan_only, store: false, or the same request within 10 minutes (cached: true). With stream: true, text/event-stream: step, result (a Chart), improved (a Chart) or error (a Problem).

idstring nullable required

chart_…; null with store: false or plan_only.

object'chart' required
type'line' | 'area' | 'bar' | 'bar_horizontal' | 'stacked_bar' | 'pie' | 'donut' | 'scatter' | 'funnel' | 'timeline' | 'kpi' | 'table' nullable required
theme'light' | 'dark' | 'editorial' | 'electric' required
locale'en' | 'es' required
compatible_typesstring[] required

The chart types this data supports.

rung'exact' | 'partial' | 'related' | 'coverage' | 'stories' nullable required

How close the chart is to what was asked. exact: the data itself, complete and verified; partial: a verified part (the podium); related: another view of the same question (the most mentioned names); coverage: the coverage or the timeline; stories: the top stories. Null for your own data.

improvingboolean required

Still looking for what was asked: the stored chart (embed, image) updates itself if it arrives. Poll GET /v1/charts/{id} or use stream: true.

embed_urlstring nullable required

An iframe that adapts to its width, with tooltips. Add ?theme= to change the theme.

image_urlstring nullable required

PNG at twice the resolution, for chat, email or slides.

svg_urlstring nullable required
svgstring nullable required

The SVG, with include_svg or store: false.

created_atstring nullable required
expires_atstring nullable required
cachedboolean required

The same request in the last 10 minutes: the same chart, not billed.

Changes

No recorded changes to this operation across all 1 revision of this API.