# Getting Started

The Image-Charts API returns a chart image in response to a URL GET or POST request. The API can generate many kinds of charts, from pie or line charts to bar charts and radars. All the information about the chart that you want, such as chart data, size, colors, and labels, are part of the URL.

To make the simplest chart possible, all your URL needs to specify is the chart type, data, and size. You can type this URL directly in your browser, or point to it with an <img> tag in your web page. For example, follow this link for a pie chart:


The preceding link is an example of a basic Chart API URL. All Chart URLs have the following format:


All URLs start with https://image-charts.com/chart? followed by the parameters that specify chart data and appearance. Parameters are name=value pairs, separated by an ampersand character (&), and parameters can be in any order, after the ?. All charts require at minimum the following parameters: cht (chart type), chd (data), and chs (chart size). However, there are many more parameters for additional options, and you can specify as many additional parameters as the chart supports.

Let’s examine the URL above in more detail:

  • https://image-charts.com/chart? This is the base URL for all chart requests. (However, see Improving Performance on Pages with Many Charts below for an optional variation for pages with multiple charts.)
  • cht=p3 The chart type: here, a 3D pie chart.
  • chs=700x100 The chart size (width x height), in pixels.
  • chd=t:60,40 The chart data. This data is in simple text format, but there are other formats.
  • chl=Hello|World The slice labels.
  • chan Animate the chart, renders a gif
  • chf=ps... Specify a linear gradient to each pie slice
  • & Parameters are separated by an ampersand. Note: When embedding an URL in HTML, for example as the src attribute of an tag, you should replace the & between parameters with the characters & This includes when you generate page HTML with PHP or some other language. However, when typing a URL in the browser, or when calling a URL in code, for example when fetching a URL in PHP or Perl, you should use the & mark.

Copy and paste this URL in your browser and try making a few changes: add additional values to the data (don’t forget to add a comma before each new data value). Add new labels (put a | mark before each new value). Make the chart bigger.

# Reference

# Feature support and roadmap

In the following documentation we will use icons to specify the state of feature support.

  • 🚧 partially supported
  • 🔧 planned, coming soon
  • 🏁 currently not planned

If you bought an Image-Charts Enterprise plan, please contact us with your requirements, it will help us prioritize our roadmap!

# Chart Size

All charts require the size to be specified. This parameter determines the total width and height of the chart image, including legends, margins, and titles. Legends, margins, and titles are clipped to fit within the total chart size.

Maximum chart size for all charts except maps is 998,001 pixels total (Google Image Charts was limited to 300,000), and maximum width or length is 999 pixels.

Values are integers.

# Syntax

  • <width> width, in pixels. Maximum value is 999. Width x height cannot exceed 998,001.
  • <height> height, in pixels. Maximum value is 999. Width x height cannot exceed 998,001.

# Example

Here is a 700 pixel x 200 pixel chart.


# Chart Type

Specify the chart type using the cht parameter. See the individual chart documentation pages for a list of available chart types.

# Syntax

  • <type> one of the chart type values. Full list of supported values are available in the API tester.
  • :nda [Optional, line charts only] You can add :nda after the chart type in line charts to hide the default axes.

# Example

A vertical bar chart


A pie chart:


A line chart without default axes:


# Data Format

This document explains how to send your chart data to the Image Charts API.

Data for almost all charts is sent using the chd parameter. The data must be sent in one of the following formats:

  • Basic text format is essentially simple floating point numbers from 0—100, inclusive. This format is easy to read and write by hand.
  • Text format with automatic scaling scales the chart to fit your data.
  • Text format with custom scaling is similar to basic text format, but it lets you specify a custom range using a second URL parameter.
  • Simple encoding format lets you specify integer values from 0—61, inclusive, encoded by a single alphanumeric character. This encoding results in the shortest data string of any of the data formats (if any values are greater than 9).
  • Extended encoding format lets you specify integer values from 0—4095, inclusive, encoded by two alphanumeric characters. Extended encoding is best suited to a chart with a lot of data and a large data range.

The data values are scaled to fit the format used; see Data Scaling and Axis Scaling for an explanation of how the data is manipulated to fit the chart.

We provide a JavaScript snippet for encoding data into simple encoding or extended encoding formats. Alternatively, several Google Chart group members have contributed other libraries to help with formatting: search the archives to find them.

# Basic Text Format

Basic text-formatted data lets you specify floating point values from 0—100, inclusive, as numbers. Values below zero are marked as missing; values above 100 are truncated to 100. The advantage of basic text format is that the values are easy to read and understand in the URL, and the default axis labels show the data values accurately. However, text formatting (whether simple or with custom parameters) results in the longest data string of all formats.

If your data includes values outside the specified range for text formatting, you can scale your data by converting it into percentages of the largest value in your data. Alternatively, you could use text formatting with custom scaling to handle the scaling for you.

# Syntax


Each series is one or more comma-separated values. Separate multiple series using a pipe character (|). Values are floating point numbers from 0—100, inclusive. Values less than zero, or the underscore character ( _ ) are considered null values. Values above 100 are truncated to 100.

# Example

A table with five values. The underscore is considered a null value, the -30 value falls below the minimum value, so it is dropped, and the 200 value is truncated to 100.


# Text Format with Automatic Scaling

You can configure some charts to scale automatically to fit their data. The chart will be scaled so that the largest value is at the top of the chart and the smallest (or zero, if all values are greater than zero) will be at the bottom.

Any marker values shown on the chart will display their actual values, not their scaled values.

This feature works only with text-formatted values, and does not work with all chart types. Experiment with your chart type to see whether it is supported.

# Syntax


Each series is one or more comma-separated values. Separate multiple series using a pipe character (|). Values are floating point numbers from 0—100, inclusive. Values less than zero, or the underscore character ( _ ) are considered null values. Values above 100 are truncated to 100.

# Example

How to generate a Pie Chart (note that you should not use values < 0 for pie charts):


How to generate a Bar Chart:


# Text Format with Custom Scaling

Text format with custom scaling lets you specify arbitrary positive or negative floating point numbers, in combination with a scaling parameter that lets you specify a custom range for your chart. This chart is useful when you don’t want to worry about limiting your data to a specific range, or don’t want to scale the data manually to fit nicely inside a chart. This format will adjust the zero line for you, as necessary. The format of the data is the same as with basic text format.

For automatic scaling, specify chds=a.

Text formatting (whether simple or with custom parameters) results in the longest data string of all formats.

# Syntax

  • chd=t: Same as plain data format: one or more comma-separated values per series, multiple series separated by a pipe character (|). The range of permitted values in each series is specified by the chds parameter.

  • chds A set of one or more minimum and maximum permitted values for each data series, separated by commas. You must supply both a max and a min. If you supply fewer pairs than there are data series, the last pair is applied to all remaining data series. Note that this does not change the axis range; to change the axis range, you must set the chxr parameter.

    • <series_1_min> The minimum allowable value in the first series. Lower values are marked as missing.
    • <series_1_max> Maximum allowable value in the first series. Higher values are truncated to this value.

# Example

A bar chart with a min/max scale of -80—140. The 30, -60, 50, 140, and 80 values fall within the scale, so they are not truncated. Note that the zero line is adjusted for you, 80/(140 + 80) = 0.36 of the way up the y-axis.

Google Image Charts had a weird bug feature, the default y-axis range was still 0—100, despite the chds parameter, so the label values do not reflected the actual data values. In Image-charts we think that its a bug. We are displaying the real-values inside the default y-axis, just as one would think.


# Simple Encoding Format

Simple encoding format lets you specify integer values from 0—61, inclusive, encoded by a single alphanumeric character. This results in the shortest data string URL of all the data formats. However, if you have a line or bar chart that is longer than 100 pixels along the data axis, you might want to use another format. This is because, with only 62 data values supported, the data granularity is much bigger than the display granularity, and values will be just little off (not much, but visible on larger charts).

Note that if you use the chds parameter with simple encoding, data element size on the chart won’t be affected, but any data point marker values will be.

# Syntax

  • <series_1> A string, where each character is a single data point, and series are delimited by a comma. Individual values within a series are not delimited. Here are the supported data characters, and their corresponding values:
    • A—Z, where A = 0, B = 1, and so on, to Z = 25
    • a—z, where a = 26, b = 27, and so on, to z = 51
    • 0(zero)—9, where 0 = 52 and 9 = 61
    • The underscore character (_) indicates a missing value

You can use the JavaScript code to scale and encode an entire URL string.

# Example

Equivalent to the text-encoded string chd=t:1,19,27,53,61,-1|12,39,57,45,51,27:


# Extended Encoding Format

Extended encoding format lets you specify integer values from 0—4095, inclusive, encoded by two alphanumeric characters. It uses a slightly different syntax from simple encoding.

Note that if you use the chds parameter with simple encoding, data element size on the chart won’t be affected, but any data point marker values will be.

# Syntax

  • <series_1> A string where each two characters is a single data point, and series are delimited by a comma. Individual values in a series are not delimited. Here are the supported encoding characters:
    • A—Z
    • a—z
    • 0—9
    • period (.)
    • hyphen (-)
    • Missing values are indicated with a double underscore (__).

Here is an abbreviated description of encoded values:

  • AA = 0, AB = 1, and so on to AZ = 25
  • Aa = 26, Ab = 27, and so on to Az = 51
  • A0 = 52, A1 = 53, and so on to A9 = 61
  • A- = 62, A. = 63
  • BA = 64, BB = 65, and so on to BZ = 89
  • Ba = 90, Bb = 91, and so on to Bz = 115
  • B0 = 116, B1 = 117, and so on to B9 = 125
  • B- = 126, B. = 127
  • 9A = 3904, 9B = 3905, and so on to 9Z = 3929
  • 9a = 3930, 9b = 3931, and so on to 9z = 3955
  • 90 = 3956, 91 = 3957, and so on to 99 = 3965
  • 9- = 3966, 9. = 3967
  • -A = 3968, -B = 3969, and so on to -Z = 3993
  • -a = 3994, -b = 3995, and so on to -z = 4019
  • -0 = 4020, -1 = 4021, and so on to -9 = 4029
  • -- = 4030, -. = 4031
  • .A = 4032, .B = 4033, and so on to .Z = 4057
  • .a = 4058, .b = 4059, and so on to .z = 4083
  • .0 = 4084, .1 = 4085, and so on to .9 = 4093
  • .- = 4094, … = 4095

You can use the JavaScript code to scale and encode an entire URL string.

# Example

Equivalent to the text-encoded string chd=t:90,1000,2700,3500|3968,-1,1100,250:


# JavaScript Encoding Script

For real-world use, it is probably easier to encode data programmatically rather than manually.

The following snippet of JavaScript encodes a single series into simple or extended encoding, and scales data values to fit within the complete range of that encoding. The data must be provided as an array of positive numbers. Any value provided that is not a positive number is encoded as a missing value by using the underscore character (_).

var simpleEncoding = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
      else {
  return chartData.join('');

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP= 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);

  return chartData;

To encode data, call the simpleEncode or extendedEncode function, passing in the array which contains your data (valueArray), and the maximum value of your data (maxValue). To create some space between the highest value and the top of the chart, set maxValue to be larger than the largest number in the data array, as follows:

var valueArray = [0,1,4,4,6,11,14,17,23,28,33,36,43,59,65];
var maxValue = 70;
simpleEncode(valueArray, maxValue);

# Color Format

Specify colors using a 6-character string of hexadecimal values, plus two optional transparency values, in the format RRGGBB[AA]. For example:

  • FF0000 = Red
  • 00FF00 = Green
  • 0000FF = Blue
  • 000000 = Black
  • FFFFFF = White

AA is an optional transparency value, where 00 is completely transparent and FF is completely opaque. For example:

  • 0000FFFF = Solid blue
  • 0000FF66 = Transparent blue

# Chart Title

You can specify the title text, color, and font size for your chart.

# Syntax


chtt - Specifies the chart title.

  • <chart_title> Title to show for the chart. You cannot specify where this appears, but you can optionally specify the font size and color. Currently basic latin and latin supplement characters are supported.

chts [Optional] - Colors and font size for the chtt parameter.

Note: Google Image Charts allowed a pipe character ( | ) to indicate line breaks in the chart titles, Image-charts does not support them and silently ignore them.

# Examples

A chart with a title, using default color and font size. Specify a space with a plus sign (+). chts is not specified here.


A chart with a blue, 20-point title.


# Grid Lines

⭐️ only bar and line charts can leverage grid lines.

You can specify solid or dotted grid lines on your chart using the chg parameter.

This parameter doesn’t let you specify the thickness or color of the lines, if you need this please contact us with your requirements.

# Syntax

  • <x_axis_enabled> if set to a number between 1 and 100 ([1;100]) enable vertical grid lines.
  • <y_axis_enabled> if set to a number between 1 and 100 ([1;100]) enable horizontal grid lines.

🏁 Google Image charts use these two parameters to calculate how many x or y grid lines to show on the chart, we decided not to implement this feature as it was hard to use and error prone.

  • <opt_dash_length>, <opt_space_length> [Optional] Used to define dashed grid lines. The first parameter is the length of each line dash, in pixels. The second parameter is the spacing between dashes, in pixels. Specify 0 for <opt_space_length> for a solid line. Default values are 4,1.

# Examples

These examples use only the <x_axis_step_size> and <y_axis_step_size> parameters. The Chart API displays a dashed grid line by default.


The following example uses larger spaces to display lighter grid lines (1,5):


Finally let’s hide the vertical grid lines from previous example:


# Chart Legend Text and Style

The legend is a side section of the chart that gives a small text description of each series. You can specify the text associated with each series in this legend, and specify where on the chart it should appear.

⭐️ A note on string values: Only URL-safe characters are permitted in label strings. To be safe, you should URL-encode any strings containing characters not in the character set 0-9a-zA-Z.

# Syntax


chdl - The text for each series, to display in the legend.

  • <data_series_label> The text for the legend entries. Each label applies to the corresponding series in the chd array. Use a + mark for a space. If you do not specify this parameter, the chart will not get a legend. There is no way to specify a line break in a label. The legend will typically expand to hold your legend text, and the chart area will shrink to accommodate the legend.

chdlp - [Optional] The position of the legend, and order of the legend entries. You can specify <position> and/or <label_order>. If you specify both, separate them with a bar character. You can add an ‘s’ to any value if you want empty legend entries in chdl to be skipped in the legend. Examples: chdlp=bv, chdlp=r, chdlp=bv|r, chdlp=bvs|r

  • <opt_position> [Optional] Specifies the position of the legend on the chart (🚧 partially supported). To specify additional padding between the legend and the chart area or the image border, use the chma parameter.
    Choose one of the following values:

    • b - [Default] Legend at the bottom of the chart, legend entries in a horizontal row.
    • t - Legend at the top of the chart, legend entries in a horizontal row.
  • <opt_label_order> [Optional] 🏁. The order in which the labels are shown in the legend.

chdls - [Optional] Specifies the color and font size of the legend text.

# Examples

How to specify legend text in the same order as your data series:


How to change legend font color and size:


# Chart Margin

You can specify the size of the chart’s margins, in pixels. Margins are calculated inward from the specified chart size (chs); increasing the margin size does not increase the total chart size, but rather shrinks the chart area, if necessary. The chart margins include the axis labels.

# Syntax

  • <left_margin>, <right_margin>, <top_margin>, <bottom_margin> Minimum margin size around the chart area, in pixels. Increase this value to include some padding to prevent axis labels from bumping against the borders of the chart.

# Example

In the example below we set a left_margin to 10px, a right_margin to 100px and a top_margin to 20px. Since we did not define bottom_margin, its value will be set to 0px.


# Axis Styles and Labels

You can specify which axes to display on the chart, and give them custom labels and positions, ranges.

Not all charts show axis lines by default. You can specify exactly which axes your chart should show using the chxt parameter. Default axis lines do not show numbers; you must specify an axis in the chxt parameter to show numbers.

You can choose to have your axes display numbers reflecting the data values, or you can specify custom axes. The default is to display numeric values, with values scaled to range from 0—100. However, you can change that range using chxr to display another range.

This section covers the following topics:

# Visible Axes

Bar, line, radar, and scatter charts show one or two axis lines by default, but these lines do not include values. To display values on your axis lines, or to change which axes are shown, you must use the chxt parameter. By default, the axis values range from 0-100, unless you scale them explicitly using the chxr property. To hide all axis lines in a line chart, specify :nda after the chart type value in the cht parameter (example: cht=lc:nda).

# Syntax

  • <axis> An axis to show on the chart. Available axes are:
    • x - Bottom x-axis
    • y - Left y-axis

Note: t (Top x-axis) and r (right y-axis) and multiple axes (e.g. x,x,y) are currently not supported.

# Example

You can suppress default axes in a line chart by specifying :nda after the chart type.


# Axis Range

You can specify the range of values that appear on each axis independently using the chxr parameter. Unlike in Google Image Charts the axis range is related to the data range, which make sense. Specifying chxr will change the scale of the chart elements.

You must make an axis visible using the chxt parameter if you want to specify its range.

# Syntax

Separate multiple axis label ranges using the pipe character ( | ).

  • <axis_index> Which axis to apply the range to. This is a zero-based index into the axis array specified by chxt. For example, the y-axis would be 1 in chxt=x,y.
  • <start_val> A number, defining the low value for this axis.
  • <end_val> A number, defining the high value for this axis.
  • <opt_step> [Optional] The count step between ticks on the axis. If there is no default step value; the step is calculated to try to show a set of nicely spaced labels.

# Example

This example shows both x and y axes (chxt).

Each axis has a defined range. Because no step is specified, values are taken from the given range and are evenly spaced within that range. In the line chart, values are evenly spread along the x-axis.

Y axis will have a range from 0 to 100 (chxr).


In this example, we are defining values (chd) from -30 to 50 and allowing them in the scale of -100,100 (chds).

The Y axis range (chxr) is set from -50 to 50 and both axis are visible (chxt).


# Custom Axis Labels

You can specify custom string axis labels on any axis, using the chxl parameter. You can specify as many labels as you like. If you display an axis (using the chxt parameter) and do not specify custom labels, the standard, numeric labels will be applied. To specify a custom numeric range, use the chxr parameter instead.

To set specific locations along the axis for your labels, use the chxp parameter.

# Syntax

Specify one parameter set for each axis that you want to label. Separate multiple sets of labels using the pipe character (|).

  • <axis_index> Which axis to apply labels to. This is an index into the chxt parameter array. For example, if you have chxt=x,x,y,y then index 0 would be the first x-axis, 1 would be the second x-axis. Currently only customizing the x-axis is supported.
  • <label_1>| ... |<label_n> One or more labels to place along this axis. These can be string or number values; strings do not need to be in quotes. label_1 is displayed at the lowest position on the axis, and label_n is displayed at the highest position. Additional labels are spaced evenly between them. Indicate spaces with a + mark. There is no way to specify a line break in a label. Separate labels with a pipe character. Note: Do not place a pipe after the final label in the chxl parameter.

# Example

This example shows how to add custom labels to two axes. Note how the values are evenly spaced, and how the last chxl value does not end with a pipe.


# Axis Label Styles

You can specify the font size, color for axis labels, both custom labels and default label values. All labels on the same axis have the same format. If you have multiple copies of an axis, you can format each one differently. You can also specify the format of a label string, for example to show currency symbols or trailing zeroes.

# Syntax

Values for multiple axes should be separated using a pipe character ( | ).

  • <axis_index> The axis to which this applies. This is a zero-based index into the chxt parameter.
  • <opt_format_string> [Optional] This is an optional format string that, if used, follows immediately after the axis index number without an intervening comma. It starts with a literal letter N followed by the following values, all optional: The formatting string syntax is as follows:
    N<preceding_text>*<number_type><decimal_places>zs<x or y>*<following_text>
    Here is the meaning of each element:
    • <preceding_text> - Literal text to precede each value.
    • *...* - An optional block wrapped in literal asterisks, in which you can specify formatting details for numbers. The following values are supported, and are all optional:
      • <number_type> - The number format, for numeric values. Choose one of the following:
        • f - [Default] Floating point format. Consider specifying precision as well with the <decimal_places> value.
        • p - Percentage format. A % sign is appended automatically. Note: When using this format, data values from 0.0 — 1.0 map to 0 — 100% (for example, 0.43 will be shown as 43%).
        • e - Scientific notation format. 🏁
        • c<CUR> - Format the number in the currency specified, with the appropriate currency marker. Replace with a three-letter currency code. Example: cEUR for Euros. You can find a list of codes on the ISO web site, although not all symbols are supported.
      • <decimal_places> - An integer specifying how many decimal places to show. The value is rounded (not truncated) to this length. Default is 2.
      • z - Display trailing zeros. Default is no.
      • s - Display group separators. Default is no.
      • x or y -Display the data from the x- or y-coordinate, as specified. The meaning of x data varies by chart type: experiment with your chart to determine what it means. Default is ‘y’.
    • <following_text> - Literal text to follow each value.
  • <opt_label_color> The color to apply to the axis text (but not axis line), in RRGGBB hexadecimal format. Axis line color is specified separately using opt_axis_color. Default is black.
  • <opt_font_size> [Optional] specifies the font size in pixels. This parameter is optional.
  • <opt_alignment> [Optional] Label alignment. 🏁
  • <opt_axis_or_tick> [Optional] 🏁 Whether to show tick marks and/or axis lines for this axis. .
  • <tick_color> [Optional] The tick mark color, in RRGGBB hexadecimal format. Default is black.
  • <opt_axis_color> [Optional] 🏁 The color of this axis line, in RRGGBB hexadecimal format. .

# Example

Display the x-axis labels in #FF00FF with a 13px font-size and #FF0000 color for the y-axis.


Chart below has an x-axis with 1 trailing zero (z) colored in black with 10px font-size and an y-axis with a $ currency suffixed by Mil, colored in #007939 with a 20px font-size.


# Background Fills

You can specify fill colors and styles for the chart data area and/or the whole chart background. Fill types include solid fills, striped fills, and gradients. You can specify different fills for different areas (for example, the whole chart area, or just the data area). The chart area fill overwrites the background fill. All fills are specified using the chf parameter, and you can mix different fill types (solids, stripes, gradients) in the same chart by separating values with pipe character ( | ). Chart area fills overwrite chart background fills.

# Solid Fills

You can specify a solid fill for the background and/or chart area, or assign a transparency value to the whole chart. You can specify multiple fills using the pipe character (|).

# Syntax

  • <fill_type> The part of the chart being filled. Specify one of the following values:
    • bg - Background fill
    • c - Chart area fill. (🏁, currently same as bg, bg as precedence over c)
    • a - Make the whole chart (including backgrounds) transparent. The first six digits of are ignored, and only the last two (the transparency value) are applied to the whole chart and all fills.
    • b<index> - Bar solid fills (bar charts only). Replace with the series index of the bars to fill with a solid color. The effect is similar to specifying chco in a bar chart (note that chf has precedence over chco for each series). See Bar Chart Series Colors for an example.
  • s Indicates a solid or transparency fill.
  • <color> The fill color, in RRGGBB[AA] hexadecimal format. For transparencies, the first six digits are ignored, but must be included anyway.

# Examples

This example fills the chart background with pale gray (EFEFEF).


This example applies a 50% transparency to the whole chart (80 in hexadecimal is 128, or about 50% transparency). Notice the table cell background showing through the chart.



This example fills the bar chart with a pale gray (EFEFEF). This was implemented for compatibility with Google Image Charts but we recommend you to use chco for series colors.


# Gradient Fills

You can apply one or more gradient fills to chart areas or backgrounds. Gradient fills are fades from a one color to another color. (Pie: background only.)

Each gradient fill specifies an angle, and then two or more colors anchored to a specified location. The color varies as it moves from one anchor to another. You must have at least two colors with different <color_centerpoint> values, so that one can fade into the other. Each additional gradient is specified by a <color>,<color_centerpoint> pair.

# Syntax

  • <fill_type> The chart area to fill. One of the following:
    • bg background fill
    • c chart area fill. (🏁, currently same as bg, bg as precedence over c)
    • b<index> gradient fills (valid in bar, line and pie charts unlike Google Image Charts which only supported bar charts). Replace with the series index of the bars to fill with a gradient. See Bar Chart Series Colors for an example.
      • lg Specifies a gradient fill.
      • <angle> a number specifying the angle of the gradient from 0 (horizontal) to 90 (vertical).
      • <color> the color of the fill, in RRGGBB[AA] hexadecimal format.
      • <color_centerpoint> specifies the anchor point for the color. The color will start to fade from this point as it approaches another anchor. The value range is from 0.0 (bottom or left edge) to 1.0 (top or right edge), tilted at the angle specified by .
    • ps<index>-<sliceIndex> (only valid in pie charts) same as b<index> but let you specify a gradient per pie slice. For pie charts, b<index> has precedence over ps<index>-<sliceIndex>, both can’t be combined as would not make much sense.

# Examples

This example displays a chart area with an horizontal linear gradient, specified with an angle of zero degrees (0). The colors are peach (FFE7C6), centered on the left side (position 0.0) and blue (76A4FB) centered on the right side (position 1.0). The chart background is drawn in gray (EFEFEF).

  76A4FB,1 (blue)

This example displays a Chart area with a diagonal (bottom left to top right) linear gradient, specified with an angle of forty-five degrees (45).
Peach (FFE7C6) is the first color specified. The bottom left of the chart is pure peach.
Blue (6A4FB) is the second color specified. The top right of the chart is pure blue. Note how we specify an offset of 0.75, to provide a peak of blue that fades away towards the top right corner.
The chart background is drawn in gray (EFEFEF).

  FFE7C6,0, (peach)
  76A4FB,0.75 (blue)

The example shows how to use gradient fills in chart series.


# Striped fills

🏁 We have no plan to support striped fills, if present, a solid fill will be used with the first color value of the stripe.

# Chart Gif Animation

Animated charts are awesome right? Sadly chart generated images are simple PNGs and our team at Image-Charts was quite sad with that status quo. But then we thought, why don’t we generate animated gif? They will perfectly fit inside emails and IM bot and will give the final wow effect everyone is waiting for!

So we did it and we were like:


# Syntax

There are two ways to use the chan parameter.

The first one is to specify an empty value. The resulting chart will be an animated gif with default duration and easing parameters:


The other way is to specify duration and easing:

  • duration_ms (optional) animation duration in milliseconds. The duration must be set between 10ms and 1500ms (1,5 seconds). Default value is 1200ms (1,2 seconds).
  • easing (optional) animation easing, it must be on of the following values (case-sensitive) easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint, easeInSine, easeOutSine, easeInOutSine, easeInExpo, easeOutExpo, easeInOutExpo, easeInCirc, easeOutCirc, easeInOutCirc, easeInElastic, easeOutElastic, easeInOutElastic, easeInBack, easeOutBack, easeInOutBack, easeInBounce, easeOutBounce, easeInOutBounce.

# Examples

💡 Quick tip: if you missed the animation, copy the image URL, paste it into another tab and then hit reload any time you want to replay the gif animation.

Let’s start with a simple chart that we animate just by adding chan to the URL:



The animation seems a little too slow, so let’s specify a duration to 1 second (1000ms):



That’s better, now let’s change the easing to easeOutBack:




# Output Format

Unlike Google Image Charts API, the output format (png or gif) will not depends on the chof query parameter but instead on whether or not the chart is animated or not, see the animation section.

However we kept it because some software like Flowdock, Slack or Facebook messenger (and so on…) needs an URL that ends with a valid image extension file to display it as an image. So we recommend you to always use the chof parameter at the end the URL to support them. Valid values are .png and .gif.


# Post Requests

Specifying your chart as a URL in your browser or an <img> tag is called a GET request. Making a GET request is simple, but GET URLs are limited to 2K characters. What if you have more data than that?

Luckily, the Chart API supports HTTP POST for chart requests up to 100 Kilobytes long (Google Image Charts API limit was 16Ko). The trade-off is the added complexity of using POST.

Here’s an example of the most basic kind of POST request: using a <form> element:

<form action='https://image-charts.com/chart' method='POST'>
    <input type="hidden" name="cht" value="lc"  />
    <input type="hidden" name="chtt" value="This is my chart"  />
    <input type='hidden' name='chs' value='300x200' />
    <input type="hidden" name="chxt" value="x" />
    <input type='hidden' name='chd' value='t:40,20,50,20,100'/>
    <input type="submit" />

Demo on JSFiddle.

The response to a valid POST request is a PNG chart, the same as a GET request response.

There are a number of ways to use POST, and all of them require additional coding either in the page code or on the server hosting the page. To use POST, you will typically create a separate page for each chart, and embed or link to these pages in your main page using <iframe> or as an <img> tags as shown below.

Here are examples of using POST with both JavaScript and PHP.

# Using JavaScript for POST Requests

The easiest way to make a JavaScript POST request is to create a page that hosts a form with chart data in <input> elements, and have the page POST the request in its onLoad() handler, and the page will be replaced by the chart PNG. The page that hosts this chart should include this page using an <iframe>. Here’s the code for the chart page:


<html xmlns="http://www.w3.org/1999/xhtml">
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <script type='application/javascript'>
    // Send the POST when the page is loaded,
    // which will replace this whole page with the retrieved chart.
    function loadGraph() {
      var frm = document.getElementById('post_form');
      if (frm) {
  <body onload="loadGraph()">
    <form action='https://image-charts.com/chart' method='POST' id='post_form'>
      <input type='hidden' name='cht' value='lc'/>
      <input type='hidden' name='chtt' value='This is my chart'/>
      <input type='hidden' name='chs' value='300x200'/>
      <input type='hidden' name='chxt' value='x'/>
      <input type='hidden' name='chd' value='t:40,20,50,20,100'/>
      <input type='submit'/>

Demo on JSFiddle.

If you use a

element, you do not need to URL-encode your strings.).

This chart can then be loaded into another page by using an <iframe> in your host page, such as this:


<iframe src="post_chart.html" width="300" height="200"></iframe>

# Using PHP for POST Requests

Most server-side languages support explicit POST requests. Here’s an example of making a POST request using PHP. This example demonstrates a page that generates a line chart with 150 random values. To use this yourself, you would customize the $chart array to include your own values.


  // Create some random text-encoded data for a line chart.
  header('content-type: image/png');
  $url = 'https://image-charts.com/chart';
  $chd = 't:';
  for ($i = 0; $i < 150; ++$i) {
    $data = rand(0, 100000);
    $chd .= $data . ',';
  $chd = substr($chd, 0, -1);

  // Add data, chart type, chart size, and scale to params.
  $chart = array(
    'cht' => 'lc',
    'chs' => '600x200',
    'chds' => '0,100000',
    'chd' => $chd);

  // Send the request, and print out the returned bytes.
  $context = stream_context_create(
    array('http' => array(
      'method' => 'POST',
      'content' => http_build_query($chart))));
  fpassthru(fopen($url, 'r', false, $context));

Embedding this chart is easier than the JavaScript example, because you can simply point to your POST page with an <img> tag, as shown here:


<img width='600' height='200' src='chartserver-image.php'>

# 🔧 Bar Charts

🔧 we are currently implementing this feature.

This section describes the various types of bar charts that you can create using the Image Chart API.

# Overview

There are a variety of bar charts that you can create, including vertical, horizontal, grouped, stacked versions of each.

Bar charts are good for side-by-side comparison and spotting trends in a small number of discrete data points. They’re a good alternative to line charts when you have only a few data points in a series.

There are three general ways to show multiple series in a bar chart:

  • Grouped vertically bvg


  • Grouped horizontally bhg


  • Stacked vertically bvs


  • Stacked horizontally bhs

🏁 Google Image Charts supported the bvo chart type in which vertical bars were stacked in front of one another. This type of chart is not planned to be supported and will automatically falls back to the bvs type.

# Series Colors

You can specify the colors of individual bars, individual series, or multiple series using the chco parameter. If you don’t specify a different color for each series, all series will be the same color.

# Syntax

chco=<series_1_color>, ..., <series_n_color>
  • <color>: An RRGGBB[AA] format hexadecimal number to apply to a series or individual bar. To apply the color to the whole series, it should be comma-delimited. To apply the color to an individual bar, it should be pipe-delimited. You can mix these two formats. See the table below for examples. Whenever you have fewer color values than data points or series, the colors will cycle through the list again, starting from the first color in that group.

# Examples

One color per series, with comma-delimited colors. chart


One color per value, with pipe-delimited colors. chart


A combination of series colors and individual bar colors.

This example shows a bar chart with two series. The first series all black (000000,) and comma-delimited. The second series is pipe-delimited, and assigns a different color for each point (FF0000|00FF00|0000FF).


This example demonstrates setting different colors for every bar in a multi-series chart.


You can also specify fills to color a series with solid, striped, or gradient colors. Solid fills look the same as using chco, but stripes or gradients create unique effects.



# 🔧 Line Charts

🔧 we are currently implementing this feature.

This section describes the various types of line charts that you can create using the Image Chart API.

# Chart Types

There are a variety of line charts that you can create. Specify a line chart with the following syntax:

# Syntax


Where <chart_type> is one of the the following types:

  • lc A line chart where data points are spaced evenly along the x-axis. Axis lines are shown by default. To show values on the axis lines, you must specify chxt.
  • ls Similar to lc charts, but by default does not display axis lines. These are also known as sparklines.
  • lxy Lets you specify both x- and y-coordinates for each point, rather just the y values.

To specify data points for lxy charts, you must specify series in multiples of two. The first series in each pair is the x coordinates for that line, and the second series is the corresponding y coordinates for that line. For example:


To space the data points evenly along the x-axis only, provide a single undefined value for the x set for that series. In this example, the red “Unicorns” line spaces the data points evenly along the x-axis. For more information about undefined values, see Data formats.

In this example, the “Ponies” line specifies exact x- and y-values for all points, and the “Unicorns” line spaces the values evenly along the x-axis.


# Data Granularity

Take care not to overestimate the number of data points required for your line chart. For example, to show how popular chocolate ice cream was over the last ten years, aggregating search queries for each day would result in more than 3,600 values. It would not make any sense to plot a graph at this granularity. On a chart 1024 pixels wide, one data point would be about a quarter of a pixel. (Additionally, this would be too much data to pass in a URL). The following examples illustrate this point.

600 pixel wide chart with 40 data points (15 pixels per data point):


300 data points (2 pixel per data point):


600 data points (1 pixel per data point):


900 data points (less than 1 pixel per data point):


# Series Colors

You can specify the colors of a specific series, or all series, using the chco parameter.

# Syntax

chco=<color_1>, ... <color_n>
  • <color> An RRGGBB[AA] hexadecimal format format hexadecimal number. Specify a single value to apply the same color to all series. Specify different colors for different series by adding color values separated by a comma. If you have fewer colors than you have series, the unspecified series will cycle through the specified colors from the beginning.

# Example

When you specify a single color for each series, each series gets the color assigned. This example has three data series and three colors specified.


The following example also has three data series, but only two colors are specified. Because the color for the third series is unspecified, the third line is drawn using the first color (red).


# Line Styles

You can specify line thickness and solid/dashed style with the chls parameter. This parameter can only be used to style lines in line or radar charts; you cannot use it to style the line in a compound chart lines, unless the base type of the compound chart is a line chart.

# Syntax

Separate multiple line styles by the pipe character (|); the first style applies to the first line, the second to the next, and so on. If you have fewer styles than lines, the default style is applied to all the unspecified lines.

  • <line_1_thickness> Thickness of the line, in pixels.
  • <opt_dash_length>, <opt_space_length> [Optional] Used to define dashed grid lines. The first parameter is the length of each line dash, in pixels. The second parameter is the spacing between dashes, in pixels. For a solid line, specify neither value. If you only specify <opt_dash_length>, then <opt_space_length> will be set to <opt_dash_length>. Default is 1,0 (a solid line).

# Examples

Here the dashed line is specified by 3,6,3 and the thicker, solid line is specified by 5:


Now let’s use various line thickness:


# Line Fills

You can fill the area below a data line with a solid color.

You can combine line fills with any other chm parameters using a pipe character ( | ) to separate the chm parameters.

# Syntax

  • <B> Fill to the bottom of the chart, fill from <start_line_index> to the bottom of the chart
  • <color> An RRGGBB format hexadecimal number of the fill color
  • <serie_index> The index of the line at which the fill starts. The first data series specified in chd has an index of zero (0), the second data series has an index of 1, and so on

# Examples

The following example fills the entire area under the line.


# Pie Charts

This section describes how to create pie charts using the Image-Chart API.

# Overview

Pie charts are good for showing simple proportional part-to-whole information. You can create a single series pie chart, where each series is made of multiple slices, or multi-series, concentric charts.

Each series describes one pie, and each data value specifies one slice. When using nested pie charts (described below), use multiple series.

To display the text associated with a slice, you will have to use either pie chart labels or a chart legend. Pie chart labels are text around the chart with lines pointing toward the slice. Legends are text associated by color.

  • Labels
  • Legend
  • Labels and Legend

Values are displayed relative to each other: so a chart with values 1,2,3 will look the same as a chart with values 100,200,300. However, when using text format data, values greater than 100 are trimmed to 100, so you will need to use text format with custom scaling to display slices greater than 100 properly (use the chds parameter with min/max values of chds=0,).

Negative values display as empty slices of the appropriate size.

# Chart Types

Specify a pie chart with the following syntax:

# Syntax


Where <chart_type> is one of the the following types:

  • p: Two dimensional pie chart. Supply one data series only; subsequent data series will automatically generate a concentric pie chart pc.

By default, pie segment colors are interpolated from pink to pale yellow. Specify other colors as described in Series Colors. Specify labels with chl as described in Pie chart labels.

  • p3: A three-dimensional pie chart. 🏁 this type of chart is not planned to be supported and will automatically falls back to the flat pie chart p type.

  • pc: A concentric pie chart. Once more than 1 data serie is specified, a concentric chart is automatically selected by Image-Charts, the first serie will be displayed on the border while the last serie will be displayed in the center.

  • pd: A doughnut pie chart.

# Series Colors

You can specify the colors of all values, each value, or some values using the chco parameter.

# Syntax

  • <color> Slice colors in RRGGBB[AA] hexadecimal format. Specify a single series color and all slices in that series will be colored in gradations of that color from darkest (first data member) to lightest (last data member). Specify two or more colors delimited by a | to describe individual slice colors. When you have multiple series (that is, a chart with concentric rings), you can specify values for different series by separating values by a comma. When fewer slice/series colors are given than slices/series displayed, then the chart will cycle through from the beginning of the slice list for the series, or the series list for the chart. You cannot specify a distinct gradient for each series in a multi-series chart.

# Examples

Specify a single color to have gradations from darkest (first slice) to lightest (last slice).


Defining a gradient; here, from yellow to red.


Defining individual slice colors; specify one color per slice.


The following chart has two data series, but specifies a single gradient per series.


Finally, here’s a concentric chart that includes both series colors and individual slice colors. The chart has two concentric data series. In human-readable form, the colors are chco=blue|yellow|green,blue|pink. The comma breaks this into two series:

  • orange|yellow|green - One color defined for each slice.
  • blue|pink - Alternating blue and yellow slices.

# Labels

You can specify labels for individual pie chart slices using the chl parameter. You can also display a legend with the same or different values, one legend entry per slice.

⭐️ A Note on String Values: Only URL-safe characters are permitted in label strings. To be safe, you should URL-encode any strings containing characters not in the character set 0-9a-zA-Z.

# Syntax

  • <label_value> A string value to apply to a slice. Labels are applied consecutively to the data points in chd. If you have multiple series (for a concentric pie chart, for example), labels are applied to all points in all sequences, in the order specified in chd. Use a pipe delimiter ( | ) between each label. Specify a missing intervening value by using two consecutive pipe characters with no space between them: || . You do not need to label all slices.

Note: unlike Google Image Charts you won’t need to anticipate how much room your need to display labels entirely. Image-charts automatically scale the graph to display labels.

# Examples

Let specify labels for a simple animated pie chart.


Same as the previous chart but this time as an animated donught chart.


And now a concentric pie charts with labels for each slices.


# Inside label

Doughnut charts have a special parameter chli that gives you the ability to add an inside label.

# Syntax

  • <label_value> A string value to apply to the doughnut inside label.

# Example

It’s always nice to display the overall data summary directly inside the doughnut.


Now, let’s animate it. Note how nicely the easeOutBounce animation easing is applied to the inside label!


# Enterprise version 🚀

This section is dedicated to the paying enterprise version. This plan use the same API but is watermark free and you can setup your own sub-domain for the perfect integration.

Once subscribed to the enterprise plan you will receive an account id and a secret key. These two keys are mandatory to sign your request and remove the watermark.

# Remove Image-Charts watermark by signing URLs

Signing request must be done server-side otherwise anyone will be able to reuse your secret key. Beside signing there are no other process involved server-side. Image-Charts is still the fastest option compared to server-side charts setup and generation.

You will need to sign the url using HMAC-SHA256 hash algorithm. Before hashing the URL add your account id inside it using the &icac=YOUR_ACCOUNT_ID parameter, then hash it and at the resulting hash in the &ichm=GENERATED_HASH query parameter. Don’t forget to convert URL-unsafe characters before generating the signature.

As an example here is a graph signed, without watermark:


Signing your URLs will ensure that no-one beside you created it and Image-Charts will verify the generated hash to be sure you your account created it. Here are some examples in various languages:

# Online Url Generator

The easiest way to generate a watermark-free Image-Charts is to use our online url generator.

# NodeJS 6+

// HMAC Helper
const crypto = require('crypto');
const qs = require('querystring');

function sign(secretKey, query) {
  return crypto
    .createHmac('sha256', secretKey)

// Now let's generate a chart url that will be sent inside an email or a bot message

// First setup our account

// Then generate the watermark-free url
// qs.stringify will encode URL-unsafe characters for us
const rawQuerystring = qs.stringify({
  cht: 'bvs',
  icac: ACCOUNT_ID, // don't forget to add your account id before signing it
  chd: 's:93zyvneTTO',
  chs: '400x401',
const signature = sign(SECRET_KEY, rawQuerystring);
const publicUrl = `https://image-charts.com/chart?${rawQuerystring}&ichm=${signature}`;

// Finally send it to slack or via email, here we simply use console.log

# Python 3

# -*- coding: utf-8 -*-

from urllib.parse import urlencode
import hmac, hashlib, codecs

def sign(query, secretKey):
  return codecs.getencoder('hex')(hmac.new(secretKey.encode('utf-8'), query.encode('utf-8'), hashlib.sha256).digest())[0].decode('utf-8')

if __name__ == '__main__':
  # First setup our account

  # Then generate the watermark-free url
  # urlencode will encode URL-unsafe characters for us
  rawQuerystring = urlencode({
      'cht': 'bvs',
      'chd': 's:93zyvneTTO',
      'chs': '400x401',
      'icac': ACCOUNT_ID  # don't forget to add your account id before signing it
  signature = sign(rawQuerystring, SECRET_KEY)
  publicUrl = "https://image-charts.com/chart?" + rawQuerystring + "&ichm=" + signature

  # Finally send it to slack or via email, here we simply use print

# PHP 5+

function sign($query, $secretKey) {
  return hash_hmac('sha256', $query, $secretKey);

// First setup our account

// Then generate the watermark-free url
// http_build_query will encode URL-unsafe characters for us

$rawQuerystring = http_build_query(array(
  'cht' => 'bvs',
  'chd' => 's:93zyvneTTO',
  'chs' => '400x401',
  'icac' => ACCOUNT_ID  // don't forget to add your account id before signing it

$signature = sign($rawQuerystring, SECRET_KEY);
$publicUrl = 'https://image-charts.com/chart?' . $rawQuerystring . '&ichm=' . $signature;

// Finally send it to slack or via email, here we simply use print
echo $publicUrl;


Because Image-charts aims to be a drop-in-replacement for Google Image Charts, this documentation is heavily based on the original Google documentation.