QuickChart Documentation
QuickChart is a web service that generates chart images on-the-fly. These images are suitable for embedding in email, SMS, chatbots, and other formats. Charts are rendered by Chart.js, a popular open-source charting library.
Do you have questions? Don't hesitate to send us a message or open a Github issue.
QuickChart works by taking Chart.js configurations and rendering them on the backend as an image. You may send your chart configuration using HTTP GET or POST requests.
For example, take this simple Chart.js configuration:
{
type: 'bar', // Show a bar chart
data: {
labels: [2012, 2013, 2014, 2015, 2016], // Set X-axis labels
datasets: [{
label: 'Users', // Create the 'Users' dataset
data: [120, 60, 50, 180, 120] // Add data to the chart
}]
}
}
We'll pack this Chart.js object into the /chart
endpoint URL:
The URL generates this chart image, a rendering of the Chart.js config above:
You can easily make adjustments to this example: try editing the chart and replacing "bar" with "line" or "pie" to get different types of chart, change the legend labels, or add another dataset to get a grouped bar chart.
Because QuickChart is built on open-source chart libraries, our charts are flexible and highly customizable. Explore the documentation below to learn more or view more examples.
The chart endpoint https://quickchart.io/chart
accepts these query parameters:
chart
: Javascript/JSON definition of the chart. Use a Chart.js configuration object. Abbreviated as "c"
You should URL-encode your chart configuration. If not encoded, you may run into problems with special characters or syntax errors in your program. You may also use base64 encoding (see encoding
option).
width=500
: Width of the image. Abbreviated as "w"height=300
: Height of the image. Abbreviated as "h"devicePixelRatio=2.0
: Device pixel ratio of the output (defaults to retina=2.0). Width and height are multiplied by this value.backgroundColor=transparent
: Background of the chart canvas. Accepts rgb (rgb(255,255,120)
), colors (red
), and url-encoded hex values (%23ff00ff
). Abbreviated as "bkg"format=png
: Format of your output. Supported output formats are PNG, WebP, and PDF. Abbreviated as "f"encoding=url
: Encoding of your "chart" parameter. Accepted values are url
and base64
.version=2.9.3
: Chart.js version to use. Currently only 2.9.3 is supported.
Combine these parameters in your query string. For example: /chart?width=500&height=300&format=pdf&c={...}
. If you are using Javascript or Python, you also have the option of using a client library instead of constructing the URL yourself.
Errors that prevent the chart from rendering will return an HTTP status code 500. In most cases, the error will be rendered in the requested image format. If an error is rendered in an image, it is also included as a string in the X-quickchart-error
HTTP header.
An example error due to invalid chart config - not URL encoded.
Invalid or unexpected token: Invalid Chart.js configurations may return errors similar to this one. The most common cause of this error is that the caller forgot to URL-encode the chart
variable. The next most common cause is invalid JSON/Javascript syntax in the chart configuration.
Cannot read property <X> of undefined and <X> is not a function: Access to certain Chart.js internals, used especially in plugins, is restricted due to potential for abuse. Contact us to get whitelisted for these features.
If your chart is large or complicated, you may prefer to send a POST request rather than a GET request. This avoids limitations on URL length and means you don't have to worry about URL encoding. The /chart
POST endpoint takes the same parameters as above via the following JSON object:
{
"backgroundColor": "transparent",
"width": 500,
"height": 300,
"format": "png",
"chart": {...},
}
Note that if you want to include Javascript code in chart
(e.g. to format labels), you'll have to send the entire chart
parameter as a string rather than a JSON object. For examples, see documentation on using JS Functions.
You may want to create a shorter URL for your charts, especially if you are sending them via email or SMS. To generate a short URL for your chart, send a POST request to https://quickchart.io/chart/create
per the above POST spec.
Here's an example using curl. You can use any library that sends an HTTP POST request:
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"chart": {"type": "bar", "data": {"labels": ["Hello", "World"], "datasets": [{"label": "Foo", "data": [1, 2]}]}}}' \
https://quickchart.io/chart/create
Here's an equivalent request using Python:
import json
import requests
quickchart_url = 'https://quickchart.io/chart/create'
post_data = {'chart': {'type': 'bar', 'data': {'labels': ['Hello', 'World'],
'datasets': [{'label': 'Foo', 'data': [1, 2]}]}}}
response = requests.post(
quickchart_url,
json=post_data,
)
if (response.status_code != 200):
print('Error:', response.text)
else:
chart_response = json.loads(response.text)
print(chart_response)
You will get a response that looks like this:
{
"success": true,
"url": "https://quickchart.io/chart/render/9a560ba4-ab71-4d1e-89ea-ce4741e9d232"
}
Go to the url in the response to render your chart.
Note the following caveats:
Using QuickChart is just a matter of creating a simple URL or using an HTTP request, so a client library is not a requirement. We've released several optional client libraries for your convenience:
Run npm install quickchart-js
to install the QuickChart dependency. Use it like so:
const QuickChart = require('quickchart-js');
const myChart = new QuickChart();
myChart
.setConfig({
type: 'bar',
data: { labels: ['Hello world', 'Foo bar'], datasets: [{ label: 'Foo', data: [1, 2] }] },
})
.setWidth(800)
.setHeight(400)
.setBackgroundColor('transparent');
// Print the chart URL
console.log(myChart.getUrl());
Get more details on the quickchart-js project page.
Run pip install quickchart.io
to install the QuickChart dependency. Use it like so:
from quickchart import QuickChart
qc = QuickChart()
qc.width = 500
qc.height = 300
qc.device_pixel_ratio = 2.0
qc.config = {
"type": "bar",
"data": {
"labels": ["Hello world", "Test"],
"datasets": [{
"label": "Foo",
"data": [1, 2]
}]
}
}
# Print the chart URL
print(qc.get_url())
Read the full Python tutorial or see details on the quickchart-python project page.
Run gem install quickchart
to install the QuickChart Ruby gem:
require 'quickchart'
qc = QuickChart.new(
{
type: "bar",
data: {
labels: ["Hello world", "Test"],
datasets: [{
label: "Foo",
data: [1, 2]
}]
}
},
width: 600,
height: 300,
device_pixel_ratio: 2.0,
)
# Print the chart URL
puts qc.get_url
Learn more about chart generation in Ruby at the quickchart-ruby repository.
Run composer install ianw/quickchart
to install the QuickChart PHP library:
require 'quickchart'
$qc = new QuickChart(array(
'width': 600,
'height': 300,
));
$qc.setConfig('{
type: "bar",
data: {
labels: ["Hello world", "Test"],
datasets: [{
label: "Foo",
data: [1, 2]
}]
}
}');
# Print the chart URL
echo $qc->getUrl();
See the PHP QuickChart client at the quickchart-php repository.
Add the QuickChart package from NuGet. Then use the Chart
object provided by the QuickChart
namespace:
namespace QuickChartExample
{
public class SimpleExample
{
static void Main(string[] args) {
Chart qc = new Chart();
qc.Width = 500;
qc.Height = 300;
qc.Config = @"{
type: 'bar',
data: {
labels: ['Hello world', 'Test'],
datasets: [{
label: 'Foo',
data: [1, 2]
}]
}
}"
Console.WriteLine(qc.GetUrl());
}
}
}
The C# QuickChart client is available on NuGet and at the quickchart-csharp repository.
Add the QuickChart package from Maven Central. If you use Maven or Gradle, you can add it to your config (view details)).
This library provides an io.quickchart
package that contains a QuickChart
class:
import io.quickchart.QuickChart;
public class PrintUrlExample {
public static void main(String[] args) {
QuickChart chart = new QuickChart();
chart.setWidth(500);
chart.setHeight(300);
chart.setConfig("{"
+ " type: 'bar',"
+ " data: {"
+ " labels: ['Q1', 'Q2', 'Q3', 'Q4'],"
+ " datasets: [{"
+ " label: 'Users',"
+ " data: [50, 60, 70, 180]"
+ " }]"
+ " }"
+ "}"
);
System.out.println(chart.getUrl());
}
}
The Java library is open-source and accessible on Github.
We've created dozens of examples of different charts that you can edit interactively.
For a variety of useful editable examples, see the chart gallery.
Customization can be very simple. By changing type: bar
to type: line
, for example, we can instantly produce an equivalent line graph:
<img src="https://quickchart.io/chart?c={type:'bar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500]}]}}">
<img src="https://quickchart.io/chart?c={type:'line',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs', data: [50,60,70,180,190], fill:false,borderColor:'blue'},{label:'Cats', data:[100,200,300,400,500], fill:false,borderColor:'green'}]}}">
There are many other chart types as well:
<img src="https://quickchart.io/chart?c={type:'radar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500]}]}}">
<img src="https://quickchart.io/chart?c={type:'pie',data:{labels:['January','February', 'March','April', 'May'], datasets:[{data:[50,60,70,180,190]}]}}">
Pie Chart documentation. You can also use options for the Chart.js datalabels plugin.
Learn how to customize pie chart labels.
<img src="https://quickchart.io/chart?c={type:'doughnut',data:{labels:['January','February','March','April','May'],datasets:[{data:[50,60,70,180,190]}]},options:{plugins:{doughnutlabel:{labels:[{text:'550',font:{size:20}},{text:'total'}]}}}}">
Doughnut Chart documentation. You can also use options from the Chart.js doughnutlabel plugin.
Learn how to customize doughnut chart labels.
<img src="https://quickchart.io/chart?c={type:'scatter',data:{datasets:[{label:'Data 1',data:[{x:2,y:4},{x:3,y:3},{x:-10,y:0},{x:0,y:10},{x:10,y:5}]}]}}">
<img src="https://quickchart.io/chart?c={type:'bubble',data:{datasets:[{label:'Data 1',data:[{x:1,y:4,r:9},{x:2,y:4,r:6},{x:3,y:8,r:30},{x:0,y:10,r:1},{x:10,y:5,r:5}]}]}}">
Bubble is similar to Scatter except that the r
variable defines bubble radius in pixels.
Bubble Chart documentation
<img src="https://quickchart.io/chart?c={type:'radialGauge',data:{datasets:[{data:[70],backgroundColor:'green'}]}}">
View the options at chartjs-radial-gauge for customization details.
<img src="https://quickchart.io/chart?c={type:'violin', data:{labels:[2012,2013,2014,2015], datasets:[{label:'Data',data:[[12,6,3,4], [1,8,8,15],[1,1,1,2,3,5,9,8], [19,-3,18,8,5,9,9]], backgroundColor:'rgba(56,123,45,0.2)', borderColor:'rgba(56,123,45,1.9)'}]}}">
You can use violin
, boxplot
, horizontalBoxPlot
, and horizontalViolin
chart types. View the options at chartjs-chart-box-and-violin-plot for customization details. For best results, add it with a scatter plot!
<img src="https://quickchart.io/chart?c={type:'sparkline',data:{datasets:[{data:[140,60,274,370,199]}]}}">
A sparkline is a special case of line graph with axes and other labeling removed. All line graph options can be applied.
You can combine charts together by specifying different "types":
<img src="https://quickchart.io/chart?c={type:'bar',data:{labels:['January','February', 'March','April', 'May'], datasets:[{label:'Dogs',data:[50,60,70,180,190]},{label:'Cats',data:[100,200,300,400,500],},{type:'line',fill:false, label:'Potatoes',data:[100,400,200,400,700]}]}}">
This web service supports QR code generation. You can render a QR code like so:
https://quickchart.io/qr?text=Here's my text
Remember the URL-encode your text
parameter for more complex strings. The QR endpoint produces a PNG image by default. You may optionally set the query parameter format=svg
for SVG format.
Specify the whitespace around QR image in modules with query parameter margin
(defaults to 4), size
in pixels of the square QR image (defaults to 150), and error correction level with ecLevel=M
(valid values: L, M, Q, H).
If you'd like to customize the color of your QR code, use dark=000000
and light=ffffff
. The parameters must be hex color codes. Here's the same code as above but with slimmer margins, more error protection, and colors:
https://quickchart.io/qr?text=Here's%20my%20text&dark=f00
Simple chart configs are defined using only JSON, but more complex chart configs may include Javascript functions. QuickChart accepts charts containing Javascript.
If you're using a GET request, all you need to do is include your function in the chart definition. If you're using a POST request, make sure you send the chart
parameter as a string rather than a JSON object.
You may POST the following data. Note that this payload is valid JSON and the chart
object is a string containing Javascript or JSON:
{
"backgroundColor": "transparent",
"width": 500,
"height": 300,
"format": "png",
"chart": "{type:'bar',data:{labels:['January','February','March','April','May'],datasets:[{label:'Dogs',data:[50,60,70,180,190]}]},options:{scales:{yAxes:[{ticks:{callback:function(value){return'$'+value;}}}]}}}"
}
Put the above JSON in a file called chart_request.json
and send it via curl:
$ curl -X POST \
-H "Content-Type: application/json" \
-d @chart_request.json \
'https://quickchart.io/chart' > chart.png
Or use any other programming language's ability to send an HTTP POST request.
Below are a few Javascript examples showing how to build a chart definition containing a function:
Option 1: Build the config as a string, not an object. This is the most straightforward way.
const chartStr = `{
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: function(value) {
return '$' + value;
}
}
}],
},
},
}`;
console.log(encodeURIComponent(chartStr));
Option 2: Construct your chart as a JSON object. Later, substitute your Javascript function.
const chartObj = {
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: '',
}
}],
},
},
};
const myFormatterFunction = function(value) {
return "$" + value
};
const chartStr = JSON.stringify(chartObj).replace('""', myFormatterFunction.toString());
console.log(encodeURIComponent(chartStr));
Option 3: Serialize a normal Javascript object containing a function using javascript-stringify. This is probably the easiest to work with but it requires an external dependency.
const { stringify } = require('javascript-stringify');
const chartObj = {
type: 'bar',
data: {
labels: ['January', 'February', 'March', 'April', 'May'],
datasets: [{
label: 'Dogs',
data: [ 50, 60, 70, 180, 190 ]
}]
},
options: {
scales: {
yAxes: [{
ticks: {
callback: function(value) {
return '$' + value;
}
}
}],
},
},
};
console.log(encodeURIComponent(stringify(chartObj)));
QuickChart comes with several Chart.js plugins pre-installed. They are:
Use these plugins as you please in your chart config - no need to import anything extra.
As with any Chart.js chart, it's possible to add custom inline plugins by setting the plugins
attribute in your chart config.
Setting a custom plugins
object will override the plugins built into QuickChart.
Here's an example that adds some extra space between a pie chart and its legend. Note that the global Chart
object is available to the plugin:
{
"type": "pie",
"data": {
"labels": ["Yes", "No", "Maybe"],
"datasets": [{
"backgroundColor": ["#FF3784", "#36A2EB", "#4BC0C0"],
"data": [3, 24, 12]
}]
},
"plugins": [{
"beforeInit": function(chart, options) {
Chart.Legend.prototype.afterFit = function() {
// Add 50 pixels of height below the legend.
this.height = this.height + 50;
};
}
}]
}
In order to extend annotation and labeling capabilities beyond Chart.js defaults, we provide three additional Chart.js plugins: Data Labels (chartjs-plugin-datalabels), Annotations (chartjs-plugin-annotation), and Outlabels (chartjs-plugin-piechart-outlabels). These allow you to add various markup to your chart. Have a look at the documentation for each plugin to learn more about the possibilities.
An example of Chart.js data labels and annotations:
An example of the outlabeledPie
type:
It is also possible to add a logo to charts or watermark a chart. For more information, see our Watermark API.
How can I make my chart look like X?
QuickChart uses the popular open-source Chart.js library, so you can use all Chart.js documentation and Chart.js-related search terms to answer questions on how to customize your chart. If you're stuck, feel free to email us.
Do I need a license to use QuickChart?
Users of QuickChart's paid versions retain full copyright to images they generate. Charts generated by QuickChart's free version are public domain.
If you'd like to fork the code, keep in mind this project is licensed under GPLv3 and you should make your code public and retain the copyright notice. If you'd like to license QuickChart privately or commercially, or if you'd like help setting up a private instance, please get in touch.
Is this a suitable replacement for Google Image Charts?
This service is a replacement for the Google Image Charts API, which turned off on March 14, 2019. QuickChart provides a drop-in replacement for Google Image Charts documented here.
QuickChart encourages the use of Chart.js format over the deprecated Google Image Charts format. Although Chart.js doesn't match exactly with the Google Image Charts API, it is a more flexible, general-purpose charting specification. Both Chart.js and QuickChart have strong open-source communities.
We encourage developers to choose a fully open-source solution over proprietary services in order to mitigate risk and future-proof their choice of API.
How reliable is QuickChart?
This site (QuickChart.io) is widely used and generates over 16 million charts per month. It is hosted on a large cluster of redundant servers. There is a built-in rate limit of 60 charts/min (1 chart/sec) per IP for free users.
If you want to adjust rate limits or need a Service-Level Agreement with uptime guarantees, purchase a license or get in touch.
See also the QuickChart status page, which monitors uptime.
How can I contribute?
QuickChart is under active development. If you'd like to suggest a feature or modify QuickChart code, please open an issue or pull request on the QuickChart Github.