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
type
Must be "line"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLdataset_configs
Array of 1-10 dataset configurationslabel
Required, 1-50 charactersline_style
Optional: "solid", "dashed", or "dotted", defaults to "solid"color
Optional hex color, defaults to #000000point_size
Optional integer between 2-10, defaults to 4x_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truey_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truemin
Optional numbermax
Optional numberlog_scale
Optional boolean, defaults to falsedata
Array of [dateType, number] data pointsshow_legend
Optional boolean, defaults to trueconnect_null_points
Optional boolean, defaults to falsebackground_color
Optional hex color, defaults to #FFFFFFinterpolation
Optional: "linear" or "smooth", defaults to "linear"stacked
Optional boolean, defaults to falseBar Chart
type
Must be "bar"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLdataset_configs
Array of 1-10 dataset configurationslabel
Required, 1-50 characterscolor
Optional hex color or array of colors, defaults to #000000pattern
Optional pattern (solid, stripes, dots, crosshatch, diagonal, zigzag)x_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truey_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truemin
Optional numbermax
Optional numberlog_scale
Optional boolean, defaults to falsedata
Array of [string, number] data pointsshow_legend
Optional boolean, defaults to truebackground_color
Optional hex color, defaults to #FFFFFFbar_width
Optional number between 0.1 and 1.0, defaults to 0.8stack_mode
Optional: "none", "stack", or "stack_100", defaults to "none"horizontal
Optional boolean, defaults to falserounded_corners
Optional boolean, defaults to falseMap
type
Must be "map"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLdata
Array of [country_code, value] pairs. Country code must be 2-letter uppercaselow_value_color
Optional hex color, defaults to #FFFFFFhigh_value_color
Optional hex color, defaults to #00FF00Scatterplot
type
Must be "scatter"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLdataset_configs
Array of dataset configurationslabel
Required, 1-100 charactersmarker_style
Optional: "circle", "square", "triangle", defaults to "circle"x_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truey_axis
Axis configurationlabel
Required, 1-50 charactersshow_grid
Optional boolean, defaults to trueshow_line
Optional boolean, defaults to truedata
Array of [string, number, number] data pointsshow_legend
Optional boolean, defaults to truecorrelation_coefficient_visible
Optional boolean, defaults to falseTable
Country | GDP (Trillion USD) | Growth Rate (%) |
---|---|---|
1United States | 26,854.6 | 2.5 |
2China | 19,374.0 | 5.2 |
3Japan | 4,231.1 | 1.9 |
4Germany | 4,430.8 | 0.3 |
5India | 3,730.9 | 6.3 |
6United Kingdom | 3,158.0 | 0.5 |
7France | 2,936.7 | 0.9 |
8Italy | 2,186.4 | 0.7 |
9Brazil | 2,126.8 | 2.9 |
10Canada | 2,089.7 | 1.5 |
type
Must be "table"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLcolumn_configs
Array of column configurationslabel
Required, 1-50 charactersalign
Optional: "left", "center", "right", defaults to "left"width
Optional integerformat
Optional stringdata
Array of arrays containing strings or numbersstriped
Optional boolean, defaults to truehoverable
Optional boolean, defaults to truepage_size
Optional integer >= 1, defaults to 10sortable
Optional boolean, defaults to trueCounter
type
Must be "counter"title
Required, 8-140 characterssubtitle
Optional, 3-140 charactersdescription
Optional, 8-2000 characters. Supports markdown with headers, links, formatting, lists, code blocks, inline code, blockquotes, and horizontal rulesicon
Optional, valid HTTP URLvalue
Required numbertext_color
Optional hex color, defaults to #000000background_color
Optional hex color, defaults to #FFFFFFbackground_effect
Optional background effect configurationgradient_stops
Array of 2-5 gradient stopscolor
Required hex colorposition
Required number between 0-1opacity
Optional number between 0-1, defaults to 1.0direction
Optional: "horizontal", "vertical", "diagonal", "radial", defaults to "vertical"blur_radius
Optional number between 0-100, defaults to 0prefix
Optional stringpostfix
Optional stringvalue_color
Optional hex color, defaults to #000000prefix_color
Optional hex color, defaults to #000000postfix_color
Optional hex color, defaults to #000000