Data Formats

This document explains how to encode your chart data.

Table of Contents

Overview of data formats

You must encode your data using one of the following formats to send it to the Chart API:

• Text encoding supports floating point numbers from 0—100, inclusive.
• Text encoding with data scaling supports any positive or negative floating point number, in combination with a scaling parameter.
• Simple encoding lets you specify integer values from 0—61, inclusive, encoded by a single alphanumeric character. This encoding results in the shortest data string in your URL of any of the data formats (if any values are greater than 9).
• Extended encoding lets you specify integer values from 0—4095, inclusive, encoded by two alphanumeric characters. Extended encoding is best suited to a large chart, with a large data range.

Note: To encode your data programmatically in simple or extended encoding, you can use the JavaScript snippet for encoding data described below. Alternatively, several Chart API Group members have contributed other API libraries to help you - you can search the Group archives or visit the Useful links to API libraries post to find these.

Data values, axis values, and scaling

Data that you submit is subject to scaling before being rendered, as described here:

1. Data is scaled to fit the encoding range. Your data is scaled to fit the range supported by the encoding, so that the maximum data value for the encoding type will be rendered at the top of that axis, and the minimum value for the encoding type is shown at the bottom. So, for example, a bar chart value of 100 in extended encoding (range 0—4095) would be 100/4095 up the axis.

   Simple encoded data, value 100 (chd=e:Bk) Simple encoding range: 0—4095 The 100 is rendered as 100/4095 of the way up the scale.	Text encoded data, value 100 (chd=t:100) Text encoding range: 0—100 The 100 is rendered as 100/100 of the way up the scale.

2. Axis labels are added [optional]. You can also choose to display axis labels using the chxt parameter. Axis labels are not calculated to reflect the chart data, but are specified independently. The default range for the axis labels is 0—100, regardless of data values. So, for example, if you use the default axis label scale on your value of 100 in an extended encoding bar chart, the corresponding label for the bar would be 2.4 (100 / 4095 * 100). If you want the numbers on the axis to reflect actual data values, you will have to specify minimum and maximum axis values that match your encoding scale. Text encoding has a scale of 0—100 already, so you don't have to change the scale. Let's illustrate this with a few examples. Here are three charts with the same data (15,26,51,61), but different encoding types and different axis scales:

   chd=s:Paz9 Simple encoding (value range 0—61) Default axis range (0—100) Encoding range is smaller than the label axis range, so the bars don't correspond to the actual value on the axis label. However, the bars are properly proportioned to each other.	chd=s:Paz9&chxr=0,0,61,10 Simple encoding (value range 0—61) Axis range explicitly set to 0—61 Encoding range and axis range are equal, so the bars correspond to their correct value on the axis.	chd=t:15,26,51,61 Text-encoding (value range 0—100) Default axis range (0—100) Encoding range and axis range are again the same, so the accurate data values are shown on the axis, by default. Because encoding range is larger (100 units), everything is smaller than in the other charts, but in proportion.

Back to top

Text encoding

Text encoding lets you specify floating point values from 0—100, inclusive, as plaintext. Values below zero are marked as missing; values above 100 are truncated to 100. It is easy to read, and the default axis labels show the data values accurately, but also results in the longest URL of all encodings.

Integer values should be sufficient for line and bar charts up to about 500 pixels, if you allow 5 pixels per value. Include a single decimal place (35.7 for example) if you require a higher resolution. Text encoding is suitable for all types of chart regardless of size.

Syntax:

chd=t:<chart data string>

<chart data string>

One or more sets of data, separated with a pipe character (|). Data sets are floating point numbers from zero (0.0) to one hundred (100.0), separated by commas (,). Values less than zero are truncated, and considered missing values. Values above 100 are truncated to 100. Truncation happens before any scaling or axis labeling.

If your data set includes values outside the specified range for text encoding, you can scale your data by converting it into percentages of the largest value in your data set. Alternatively, you can use Text encoding with data scaling, which does the scaling for you.

Example:

chd=t:30,-30,50,80,200 The -30 value falls below the minimum value, so it is dropped, and the 200 value is truncated to 100.

Back to top

Text encoding with data scaling

Text encoding with data 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 do the calculations to scale your data down or up to fit nicely inside a chart.

Valid values range from (+/-)9.999e(+/-)100, and only four non-zero digits are supported (that is, 123400, 1234, 12.34, and 0.1234 are valid, but 12345, 123.45 and 123400.5 are not).

This encoding is not available for maps.

Syntax:

Text encoding with data scaling requires two parameters:

chd=t:<chart data string>&
chds=<data set 1 minimum value>,<data set 1 maximum value>,...,<data set n minimum value>,<data set n maximum value>

chd=t:<chart data string>

One or more sets of data, separated with a pipe character (|). Data sets are floating point numbers within the range(s) specified by the chds parameter. Values less than the specified minimum are considered missing values, and values above the maximum are truncated to the maximum value. Truncation happens before any scaling or axis labeling.

chds

A set of one or more minimum and maximum allowable values for each data series, separated by commas. If you supply fewer data scaling parameters than there are data sets, the last scaling parameter is applied to the remaining data sets. Provide just one pair of scaling parameters to apply a single range to a chart.

<data set 1 minimum value>

The minimum allowable value in the first data set. Lower values are marked as missing.

<data set 1 maximum value>

Maximum allowable value in the first data set. Higer values are truncated to this value.

<data set n minimum value>

Minimum allowable value in the nth data set. Lower values are marked as missing.

<data set n maximum value>

Maximum allowable value in the nth data set. Higher values are truncated to this value.

Example:

chd=t:30,-60,50,120,80,-90&chds=-80,140 The -90, -60, and 120 values fall within the scale, so they are not truncated. Note that the zero line is adjusted 80/140 of the way up the Y axis. The default Y axis scale is used, so the values on the axis do not show the actual data values.

Back to top

Simple encoding

Simple encoding lets you specify floating point values from 0—61, inclusive, encoded by a single alphanumeric character. This results in the shortest data string URL of all the encodings.

Allowing five pixels per data point, this is sufficient for line and bar charts up to about 300 pixels (see Guidelines for granularity below).

Syntax:

chd=s:<chart data string>

<chart_data_string>

A string where each character is a data point, and each series is delimited by a comma. Here are the supported data characters, and their 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

See Simple encoding character values for a complete listing of available characters and their values, use the JavaScript code to encode an URL string, or the following tool to encode a single value:

Example:

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

Back to top

Extended encoding

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

Syntax:

chd=e:<chart data string>

<chart data string>

A string where each two characters is a data point, and each series is delimited by a comma. Here are the supported data point characters:

• A—Z
• a—z
• 0—9
• period (.)
• hyphen (-)
• Missing values are indicated with a double underscore (__).

Here is an abbreviated description of how to represent values (to generate a complete listing, see Extended encoding character 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

Here is a tool to encode individual numbers:

Example:

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

Back to top

Encoding data with JavaScript

You will most likely find it easier to translate real-life data into Chart API data programmatically rather than manually.

The following snippet of JavaScript encodes a data set into Simple encoding. The data set 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';

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('');
}

To encode data, call the simpleEncode 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 = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

Back to top

Using multiple data series

To draw multiple lines, or sets of bars, on a chart, specify multiple data series. When using Text Encoding or Text Encoding with Data Scaling, use a pipe character (|) to separate multiple data series. When using Simple or Extended Encoding, use a comma (,) to separate multiple data series.

You can also use multiple data series as invisible guides, to accurately place labels or markers on a chart. To exclude these data series from the visible chart data, use the following:

chd=<encoding type><chart data series>:<chart data string>

Where:

• <encoding type> is one of the following:
  • t to specify Text Encoding or Text Encoding with Data Scaling.
  • s to specify Simple Encoding.
  • e to specify Extended Encoding.
• <chart data series> is the number of data series that are used to draw chart data. Other data series will not be drawn, but will be available for positioning labels or markers.
• <chart data string> is the chart data. This includes data used for drawing the chart, and data used for positioning labels or markers.

Back to top

Guidelines for granularity

Take care not to overestimate the number of data points required for a 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 3600 values. It would not make any sense to plot a graph at this granularity. On a screen that was 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.

200 by 100 chart with 40 data points (5 pixels per data point):

80 data points (only 2.5 pixels per data point):

150 data points (only 1.3 pixels per data point):

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

Back to top