Differences from using our platform

While the ChartPixel platform generates the best charts from an uploaded dataset and allows you to analyze your data and explore any chart further, the API offers the fastest way to convert data into one best or specific chart given a set of predefined columns, filters, and other options.

• Create a specific timeline chart from your data and display it on your website or blog while also being able to send periodic API calls to refresh the chart with new inputs.
• Show your customers an interactive chart within your app by directly embedding and downloading the SVG from the API call.
• Create statistically robust AI insights for your audience given a specific dataset, such as trends, data anomalies, geographic categories for revenue, and so on.
• Create a chart and insights from a table with live data on the web, and update the chart periodically to show on your blog or to your customers.
• Create a quick dashboard from a chosen set of columns that displays your chosen charts with both AI-generated titles and insights. You can update the dashboard as required by updating your data source and re-sending the API calls.

Basic example

ChartPixel API accepts request parameters as either HTTP GET or HTTP POST. For the simplest example, paste the following URL into your browser, but remember to replace the your_api_key placeholder.

curl https://www.chartpixel.com/api/v1/chart \
-H "Authorization: Bearer your_api_key" \
-d url="https://www.chartpixel.com/static/datasets/ai_salaries_2024.csv" \
-d columns=[\"Remote ratio %\",\"Salary in USD\"] \
-G
									
										

https://www.chartpixel.com/api/v1/chart?api-key=your_api_key&url=https://www.chartpixel.com/static/datasets/ai_salaries_2024.csv&output=html&columns=['Remote ratio %','Salary in USD']
										
										

#Create a secret api-key in your ChartPixel workspace
api_key = "your_api_key"

#The url that hosts your data
input_url = "https://www.chartpixel.com/static/datasets/ai_salaries_2024.csv",

#Pick on the these output types: svg/png/html
output_type = "html"

#The main endpoint to the api call
api_url = "https://www.chartpixel.com/api/v1/chart"

#Select your columns
columns = ['Remote ratio %','Salary in USD']

headers = {
	"Authorization": f"Bearer {api_key}",
	"accept": "application/json",
	"content-type": "application/json",
}

payload = {
	"url":input_url,
	"output_type":output_type,
	"columns":columns,
}



response = requests.post(api_url, json=payload, headers=headers)
print(response.json())
										
											

fetch('https://www.chartpixel.com/api/v1/chart?url=https://www.chartpixel.com/static/datasets/ai_salaries_2024.csv&output=html&columns=["Remote ratio %","Salary in USD"]', {
	headers: {
		'Authorization': 'Bearer your_api_key'
	}
	})
	.then(response => response.json())
	.then(data => console.log(data))
	.catch(error => console.error('Error:', error));

										

The input specifies the data source URL, the columns, and the desired output type. The result of the API call is a structured JSON-encoded response. It provides an chadt access url for your chart, the chart type,chart insights, and other useful parameters, such as, how many API credits you have left, or the duration of the API call.

										
{"api_credits_left": 1731, 
"available_kinds": ["abc", "sbc", "pie", "ran_avg", "ran_cat", "ran_single", "kde", "twp"], 
"chart_url": "https://www.chartpixel.com/static/api/api_demo/zjjeBcx1A-idBEopdyJzTkrKdsmN6LL1M3JTh9S2PGM.html", 
"datetime_created": "2024-04-23 17:18:55", 
"description": "The column chart shows the average Salary in USD for the three categories of Remote ratio % group. The taller the bar, the higher the average Salary in USD.\n\nAcross the three categories, the highest Salary in USD is found for #98c8f6 0 - 40 with 159.41 K, whereas the lowest Salary in USD for #77cbb3 40 - 80 with 127.56 K.\n\nMove your mouse over a column to find some more details.", 
"duration": 22, 
"filter_applied": false, 
"has_dimennsions": false, 
"has_legend": false, 
"input": "csv", 
"insight": "\n\nKey takeaway: The data suggests that there is a noticeable decrease in average salary as the remote work ratio increases. This trend should be considered when making decisions about remote work policies and salary structures.\n\nIt seems that there is a clear drop in the average salary when comparing the values for the 80 - 100 category to those for the 40 - 80 category.\n\nWhen we compare the different salary values across the categories, some of the differences may not be meaningful and could have happened by chance.\n\nFor example, the average salary of $159.41K for the 0 - 40 category is not statistically different from the average salary of $127.56K for the 40 - 80 category.\n\nEven though some of the differences in average salary are not statistically significant, the 0 - 40 category stands out as being significantly higher than the others.\n\nThe statistics (Cuzick Test) show that as the remote work ratio increases from 0 - 40 to 80 - 100, the average salary tends to get significantly smaller. This result may seem contradictory to the observed decrease in averages across the categories, but the sample size and differences are large enough to confirm this trend.", 
"kind": "abc", 
"kind_literal": "Bar chart with averages", 
"len": 14005, 
"meta": "", 
"subinfo": "", 
"subtitle": "Average Salary in USD", 
"theme": "ChartPixel Balanced", 
"title": "Remote Work Ratio vs. Average Salary Trend", 
"warnings": [], 
"x": "Remote ratio % group", 
"y": "Salary in USD"}
										
										

Creating a chart from a website

For small tables on a webpage, the ChartPixel API works more autonomously and generates a chart without the need to specify columns. Here we want render the 50 largest economies as seen on Wikipedia. We specify the url parameter pointing at the website that contains a table with the largest economies, url=https://en.wikipedia.org/wiki/List_of_countries_by_GDP_(nominal).

We also need to add &output_type=svg into the parameters to request an interactive chart, and &kind=ran as we would like a chart based on ranking.

A simple GET request would look like this:

http://www.chartpixel.com/api/v1/chart?api-key=your_api_key&url=https://en.wikipedia.org/wiki/List_of_countries_by_GDP_(nominal)&output=svg&kind=ran
	

The output is a response with the chart_rul pointing to an interactive svg.

	{"api_credits_left": 4877, 
	"available_kinds": ["na"], 
	"chart_url": "https://www.chartpixel.com/static/api/api_demo/qU9Rd0sH3TRtbZ3VBsJnAtTOjPlFDroY0js3CirK75A.svg", 
	"datetime_created": "2024-04-25 09:40:42", 
	"description": "This bar chart shows the twenty highest values for (IMF, Forecast). The bars are arranged from the highest to the lowest (IMF, Forecast).\n\nFor example, United States has the highest value with 28.781083 M.\n\nThis chart is a relatively small fraction of the full table, which has a total of 213 unique (Country/Territory records.", 
	"dimensions": [262, 200],
	"duration": 4, "filter_applied": false, 
	"has_dimennsions": true, 
	"has_legend": false, 
	"input": "web", 
	"insight": "\n\nKey takeaway: The United States has a significantly larger economy than other countries, which may indicate strong economic power and influence. The United States has the highest GDP in billion dollars compared to other countries, with a big lead over China and other countries.", 
	"kind": "ran", 
	"kind_literal": "Ranking chart", 
	"len": 213, 
	"meta": "", 
	"subinfo": "", 
	"subtitle": "Top 20 (IMF, Forecast)", 
	"theme": "ChartPixel Balanced", 
	"title": "US Leads IMF Economic Forecast Rankings", 
	"warnings": ["No columns specified. Darting in the dark.", "Couldn't match user columns. Checked the first 8 instead."], 
	"x": "(Country/Territory", 
	"y": "(IMF, Forecast)"}
	

API key

Like with most APIs, you need a secret key to make an API call. This API key helps you to keep your account secure and do an API call without the need to log in.

1. To create a secret key, navigate to the API section of your workspace and click on + Create new API key.
2. You will be asked to enter a name for your key. This name is for your own perusal and to keep track of your usage. Note that each name needs to be unique. For example, type "testkey" into the input field and click on Create.
3. Note down the key that is displayed to you. Copy and paste the key, and store it in a secure location.

API credits

To make an API call, you need to have ChartPixel credits or be subscribed. On the ChartPixel platform, credits allow you to unlock a project. However, credits can also be conveniently used for using our API. Each credit is worth 100 API calls.

Here is an example of how credit usage works. Let's say that you have 6 credits in your account. After 100 API calls, one credit will be deducted, and you will have 5 credits left. After 200 API calls, you will have 4 credits, and so on. If you have zero credits left, you cannot make more API calls until you purchase more credits.

Subscribed users can make up to 5,000 API calls per month. If you reach your limit while you are subscribed, you can purchase credits at a 50% discount.

API security

For maximum security, ChartPixel requires authentication for each API call and doesn't keep your sessions alive through the use of session tokens. Keep your secret key in a safe, and never share your key with anyone. If you stop using your API, you can delete your secret key by clicking on the trash icon in your API workspace.

ChartPixel also doesn't store your data input. The output chart can be stored both temporarily and permanently, depending on your preferences. For example, if you do not want to download a chart, but instead prefer to embed it permanently for external access on your website, dashboard, or blog, you can specify this in the API call settings.

Input parameters

If the URL is a direct link to a file, the file extension needs to be csv, xls, xlsx or fea (feather) and at most 10 MB large. If the URL is a website, the website needs to have a plain table element that is at most 10 MB large.

• url=https://www.chartpixel.com/static/datasets/ai_salaries_2024.csv
• url=https://en.wikipedia.org/wiki/List_of_highest_mountains_on_Earth

• csv: Unlike using ChartPixel on our platform, which authomatically infers the delimiters, such as semicolons or tabs, the csv file's delimiter when using the API needs to be a comnma.
• xls: For Microsoft Excel files, the first sheet is read unless it further specified with the query parameter sheet=
• fea and parquet: Feather and Parquet files based on Apache
• web: A single HTML webpage that contains at least one table. If the webpage contains more than one table, the table with the most rows is processed.
• auto: Let ChartOixel automatically infer of any of these types above by checking the extension or lack of at the end of the URL.

• svg:The chart will be rendered as an interactive svg (with tooltips showing upon hovering).
• png: The chart will be rendered as a png.
• html: The chart will be rendered as stand-alone webpage with title, and subtitle, legend, and insight.

Possible parameter values (chart type) are:

• best (ChartPixel determines the best chart)
• pps (Predictive power matrix)
• tsc (Time series plot)
• pie (Pie chart)
• ran_cat (Count plot)
• abc (Bar chart with averages)
• ran (Ranking chart)
• sbc (Stacked bar chart)
• ran_avg (Ranking chart with averages)
• kde (Kernel density plot)
• rid (Ridge plot)
• ran_sbc_single_ord (Ranked segments chart)
• ran_bool (Segmentation chart for boolean values)
• ran_single (Ranking chart)
• reg (Scatter plot)
• sco (Gauge chart from a Likert scale)
• sco_single_ord (Gauge chart from ordinal categories)
• ran_sbc_ord (Ranked combination segment chart)
• twp (Two-way plot)
• ran_sbc (Ranked stacked bar chart)
• pan (Panel data plot)
• pan_avg (Grouped time series plot)
• pan_pct_cat (Grouped time series plot with percentages)
• pan_pct (Grouped time series plot with percentages)
• pan_count (Grouped time-series counts plot)
• pan_cat_count (Grouped time series count plot with categories)
• agg_pie (Pie chart (aggregated))
• agg_abc (Bar chart (aggregated))
• wcl (Wordcloud)
• wcl_time (Word frequency timeplot)
• exp (Exploration chart)
• msb (Multi-select bar chart)
• mss (Multi-select stacked bar chart)
• sco_mult (Multi-gauge chart from likert scales)
• sco_mult_ord (Multi-gauge chart from ordinal categories)

• columns="Height (cm)"
• columns="Salary", "Date of Birth"

The filter must refer to one or more columns that have categorical values. A dict in this context refers to one or more key-value pairs, where the key is a quoted column and the value is a list of quoted categories enclosed in square brackets.

Example usage:

• filter={"Job title":["Data Scientist"]}
• filter={"Country":["US", "DE", "IN", "CA", "NL"]}
• filter={"Country":["US", "DE", "IN", "CA", "NL"], "Job title":["Data Scientist"]}

Possible parameters are ChartPixel Balanced, Corporate, Tabular 20, Colorful Light, Rainbow, Summer Pastures, Pastel, Blue Green, Classic Blue, London Sky, Barbie and Ken, Colorful Solid, Pleasing, Ocean, Tabular 10, Twilight, Posh Corporate, Gaja, GNU, Coolwarm, Magma, Flare, Spring, Corporate Camouflage, Score.

Interactivity in this context means that information is shown to the user when hovering over a chart or chart element.

Unlike the ChartPixel platform, which does a more thorough check to determine the correct encoding regardless of the data input, the API skips this check for speed. For most files, utf-8 should work.