Documentation

Getting Started

You can programmatically manage charts on Subsets via the Python SDK. This guide will help you set up the SDK and create your first chart.

Installation

Install using pip: pip install subsetsio

Authentication

To use the SDK, you'll need an API key. You can find your API key at Account Settings after logging in. New users are able to create 10000 charts.

Security Note

Never hardcode your API key or commit it to version control. Use environment variables or a secure configuration management system in production environments.

Quick Start

Charts have two required properties: data and metadata. Data is a two-dimensional array, while metadata describes how the data should be visualized. The structure and valid data types for your array will depend on which chart type you choose (see 'Chart Types' section for details).

Data Usage Rights

Before creating charts, ensure you have the necessary rights to distribute and share the data. Charts are public by default and can be viewed by anyone with the link, so avoid including sensitive business information or data you're not authorized to distribute.

API Reference

Creating Charts

Charts have two required properties: data and metadata. Data is a two-dimensional array, while metadata describes how the data should be visualized. All operations support batch processing for efficient handling of multiple charts.

Validating Charts

Before sending charts to the API, you can check if they're properly formatted. This helps catch issues early in your development process:

Batch Operations

When working with multiple datasets, you can process them all in a single API call for better performance:

Retrieving Charts

You can retrieve charts either by their specific ID or by searching with various filters and criteria.

To retrieve a specific chart by its ID:

To search for charts using filters and pagination:

Updating Charts

You can update any aspect of an existing chart - useful when you need to modify titles, change data points, or adjust visualizations.

Adding New Data Points

You can add new data points to existing charts - particularly useful for line charts when new data becomes available:

Deleting Charts

You can delete charts individually by ID or in batch. The operation is irreversible:

Syncing Charts

sync() manages the state of your charts to determine which operation to perform. It requires the tags.id property to be set to uniquely identify charts. This approach loads all charts in memory, so it's best suited for small to medium-sized jobs. It writes state to .subsets in your working directory. You can also pass a custom path to store the state file.

Chart Types

Explore different chart types available in the Subsets API. Each chart type has its own configuration options, validation rules, and example implementations.

Line Chart

Configuration
Preview

Validation Rules
typeMust be "line"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
dataset_configsArray of 1-10 dataset configurations
labelRequired, 1-50 characters
line_styleOptional: "solid", "dashed", or "dotted", defaults to "solid"
colorOptional hex color, defaults to #000000
point_sizeOptional integer between 2-10, defaults to 4
x_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
y_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
minOptional number
maxOptional number
log_scaleOptional boolean, defaults to false
dataArray of [dateType, number] data points
show_legendOptional boolean, defaults to true
connect_null_pointsOptional boolean, defaults to false
background_colorOptional hex color, defaults to #FFFFFF
interpolationOptional: "linear" or "smooth", defaults to "linear"
stackedOptional boolean, defaults to false

Bar Chart

Configuration
Preview

Validation Rules
typeMust be "bar"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
dataset_configsArray of 1-10 dataset configurations
labelRequired, 1-50 characters
colorOptional hex color or array of colors, defaults to #000000
patternOptional pattern (solid, stripes, dots, crosshatch, diagonal, zigzag)
x_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
y_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
minOptional number
maxOptional number
log_scaleOptional boolean, defaults to false
dataArray of [string, number] data points
show_legendOptional boolean, defaults to true
background_colorOptional hex color, defaults to #FFFFFF
bar_widthOptional number between 0.1 and 1.0, defaults to 0.8
stack_modeOptional: "none", "stack", or "stack_100", defaults to "none"
horizontalOptional boolean, defaults to false
rounded_cornersOptional boolean, defaults to false

Map

Configuration
Preview

Validation Rules
typeMust be "map"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
dataArray of [country_code, value] pairs. Country code must be 2-letter uppercase
low_value_colorOptional hex color, defaults to #FFFFFF
high_value_colorOptional hex color, defaults to #00FF00

Scatterplot

Configuration
Preview

Validation Rules
typeMust be "scatter"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
dataset_configsArray of dataset configurations
labelRequired, 1-100 characters
marker_styleOptional: "circle", "square", "triangle", defaults to "circle"
x_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
y_axisAxis configuration
labelRequired, 1-50 characters
show_gridOptional boolean, defaults to true
show_lineOptional boolean, defaults to true
dataArray of [string, number, number] data points
show_legendOptional boolean, defaults to true
correlation_coefficient_visibleOptional boolean, defaults to false

Table

Configuration
Preview

Country
GDP (Trillion USD)
Growth Rate (%)
1United States
26,854.62.5
2China
19,374.05.2
3Japan
4,231.11.9
4Germany
4,430.80.3
5India
3,730.96.3
6United Kingdom
3,158.00.5
7France
2,936.70.9
8Italy
2,186.40.7
9Brazil
2,126.82.9
10Canada
2,089.71.5
Page 1 of 3
Validation Rules
typeMust be "table"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
column_configsArray of column configurations
labelRequired, 1-50 characters
alignOptional: "left", "center", "right", defaults to "left"
widthOptional integer
formatOptional string
dataArray of arrays containing strings or numbers
stripedOptional boolean, defaults to true
hoverableOptional boolean, defaults to true
page_sizeOptional integer >= 1, defaults to 10
sortableOptional boolean, defaults to true

Counter

Configuration
Preview

Live BTC/USD
$69,420.50
Validation Rules
typeMust be "counter"
titleRequired, 8-140 characters
subtitleOptional, 3-140 characters
descriptionOptional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rules
iconOptional, valid HTTP URL
valueRequired number
text_colorOptional hex color, defaults to #000000
background_colorOptional hex color, defaults to #FFFFFF
background_effectOptional background effect configuration
gradient_stopsArray of 2-5 gradient stops
colorRequired hex color
positionRequired number between 0-1
opacityOptional number between 0-1, defaults to 1.0
directionOptional: "horizontal", "vertical", "diagonal", "radial", defaults to "vertical"
blur_radiusOptional number between 0-100, defaults to 0
prefixOptional string
postfixOptional string
value_colorOptional hex color, defaults to #000000
prefix_colorOptional hex color, defaults to #000000
postfix_colorOptional hex color, defaults to #000000