# Getting Started

Image-Charts Usage Policy
There’s no limit to the number of calls per day you can make to the Image Charts API. However, we reserve the right to block any use that we regard as abusive.

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:

https://image-charts.com/chart?chs=700x190&chd=t:60,40&cht=p3&chl=Hello%7CWorld&chan&chf=…

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

https://image-charts.com/chart?cht=<chart_type>&chd=<chart_data>&chs=<chart_size>&...additional_parameters...

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:

chart
https://image-charts.com/chart?
  cht=p3&
  chs=700x100&
  chd=t:60,40&
  chl=Hello|World&
  chan&
  chf=ps0-0,lg,45,ffeb3b,0.2,f44336,1|ps0-1,lg,45,8bc34a,0.2,009688,1
  • 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

chs=<width>x<height>
  • <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
chs=700x200

# Chart Type

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

# Syntax

cht=<type>[:nda]
  • <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

chart
cht=bvs

A pie chart:

chart
cht=p

A line chart without default axes:

chart
cht=ls

# 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

chd=t:val,val,val|val,val,val...

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.

chart
chd=t:_,30,-30,50,80,200

# 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

cht=t:val,val,val...
chds=a

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):

chart
chd=t:5,30,50,80,200
chds=a

How to generate a Bar Chart:

chart
chd=t:-5,30,-30,50,80,200
chds=a

# 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:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
  • 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.

chart
chd=t:30,-60,50,140,80,-90
chds=-80,140

# 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

chd=s:
  <series_1>
    ,...,
  <series_n>
  • <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:

chart
chd=s:BTb19_,Mn5tzb

# 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

chd=e:
  <series_1>
    ,...,
  <series_n>
  • <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:

chart
chd=e:BaPoqM2s,-A__RMD6

# 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 {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP= 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
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);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      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=<chart_title>
chts=<color>,<font_size>

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.

chart
chtt=Site+visitors+by+month+January+to+July

A chart with a blue, 20-point title.

chart
chtt=Site+visitors
chts=FF0000,20,r

# 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

chg=
  <x_axis_enabled>,<y_axis_enabled>,
  <opt_dash_length>,<opt_space_length>
  • <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.

chart
cht=bvg
chg=20,50
chart
cht=lc
chg=20,50

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

chart
chg=20,50,1,5

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

chart
chg=0,50,1,5

# 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=<data_series_1_label>|...|<data_series_n_label>
chdlp=<opt_position>|<opt_label_order>
chdls=<color>,<size>

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:

chart
chdl=NASDAQ|FTSE100|DOW
chco=FF0000,00FF00,0000FF
chart
chco=2196F3,FF5722,9c27b0

How to change legend font color and size:

chart
chdls=9e9e9e,17

# 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

chma=<left_margin>,<right_margin>,<top_margin>,<bottom_margin>
  • <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.

chart
chma=10,100,20

# 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,