Visualization¶

2 endpoints for generating charts from analyzed datasets and validating chart specifications without incurring render cost.

Method	Endpoint	Purpose
`POST`	`/v1/visualize`	Render a chart from a dataset — returns Plotly JSON or a hosted PNG/SVG URL
`POST`	`/v1/validate-chart`	Validate a chart spec against the dataset schema without fetching data or rendering

Python SDK Examples¶

Render a bar chart as Plotly JSON¶

from toolkitapi import Analytics

with Analytics(api_key="tk_...") as analytics:
    result = analytics.visualize({
        "dataset_id": "ds_abc123",
        "chart_spec": {
            "chart_type": "bar",
            "x": "region",
            "y": "revenue",
            "aggregation": "sum",
            "sort": {"by": "revenue", "direction": "desc"},
            "title": "Revenue by Region",
            "theme": "plotly_white",
        },
        "output_format": "plotly_json",
    })

# Pass directly to Plotly.react() in the front-end
plotly_figure = result["plotly_json"]

Export a chart as a PNG image¶

from toolkitapi import Analytics

with Analytics(api_key="tk_...") as analytics:
    result = analytics.visualize({
        "dataset_id": "ds_abc123",
        "chart_spec": {
            "chart_type": "line",
            "x": "month",
            "y": "passengers",
            "title": "Monthly Passengers",
            "width": 1200,
            "height": 600,
        },
        "output_format": "png",
    })

print(result["image_url"])  # Pre-signed object-storage URL

Validate a chart spec before rendering¶

from toolkitapi import Analytics

with Analytics(api_key="tk_...") as analytics:
    check = analytics.validate_chart({
        "dataset_id": "ds_abc123",
        "chart_spec": {
            "chart_type": "bar",
            "x": "region",
            "y": "revenue",
            "aggregation": "sum",
        },
    })

if check["valid"]:
    print("Chart spec is valid — proceed to /v1/visualize")
else:
    for err in check["errors"]:
        print("Error:", err)
for warn in check.get("warnings", []):
    print("Warning:", warn)

Request Parameters¶

POST /v1/visualize¶

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Handle returned by `/v1/analyze` or `/v1/datasets/bundle`
`chart_spec`	object	Yes	Declarative chart configuration (see sub-fields below)
`output_format`	string	No	`plotly_json` (default), `png`, or `svg`

POST /v1/validate-chart¶

Parameter	Type	Required	Description
`dataset_id`	string	Yes	Handle returned by `/v1/analyze` or `/v1/datasets/bundle`
`chart_spec`	object	Yes	Declarative chart configuration to validate

`chart_spec` sub-fields (shared by both endpoints)¶

Field	Type	Required	Description
`chart_type`	string	Yes	`bar`, `line`, `scatter`, `histogram`, `pie`, `area`, or `table`
`x`	string	No	Column name for the X-axis or category dimension
`y`	string	No	Column name for the Y-axis or value dimension
`color`	string	No	Column name used to split series by colour
`facet`	string	No	Column name used to create faceted sub-charts
`aggregation`	string	No	Aggregation applied to `y`: `sum`, `avg`, `count`, `min`, `max`, or `none`
`sort`	object	No	Sorting spec with `by` (column name) and `direction` (`asc` or `desc`)
`limit`	integer	No	Maximum number of data points after aggregation and sorting
`title`	string	No	Chart title
`x_label`	string	No	Custom X-axis label
`y_label`	string	No	Custom Y-axis label
`color_scheme`	string	No	Plotly colour palette name (e.g. `D3`, `Plotly`, `G10`)
`theme`	string	No	Plotly layout template (e.g. `plotly_white`, `plotly_dark`)
`bar_mode`	string	No	For bar charts: `group`, `stack`, or `overlay`
`width`	integer	No	Chart width in pixels
`height`	integer	No	Chart height in pixels

Response Fields¶

Visualize¶

Field	Type	Description
`plotly_json`	object \| null	Plotly figure object (data + layout). Present when `output_format` is `plotly_json`
`image_url`	string \| null	Pre-signed object-storage URL to the rendered image. Present for `png` / `svg` output
`meta`	object	Observability metadata: `request_id`, `runtime_ms`, `cache_hit`, `schema_fingerprint`

Validate Chart¶

Field	Type	Description
`valid`	boolean	`true` if the chart spec is compatible with the dataset schema and has no blocking errors
`errors`	array of strings	Blocking issues that would prevent rendering (e.g. column not found)
`warnings`	array of strings	Non-blocking advisory messages (e.g. high-cardinality colour dimension)

Tip

Call /v1/validate-chart first whenever user or agent input is involved. Validation is schema-only — no rows are scanned and no render cost is incurred. Image output formats (png, svg) require object storage to be configured on your account.

Query & Analysis

Export & Bundles