Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
URI::GoogleChart(3)   User Contributed Perl Documentation  URI::GoogleChart(3)

       URI::GoogleChart	- Generate Google Chart	URIs

	use URI::GoogleChart;
	my $chart = URI::GoogleChart->new("lines", 300,	100,
	    data => [45, 80, 55, 68],
	    range_show => "left",
	    range_round	=> 1,

	# save chart to	a file
	use LWP::Simple	qw(getstore);
	getstore($chart, "chart.png");

	# or embed chart in an HTML file
	use HTML::Entities;
	my $enc_chart =	encode_entities($chart);

	open(my	$fh, ">", "chart.html")	|| die;
	print $fh qq(
	    <h1>My Chart</h1>
	    <p><img src="$enc_chart"></p>
	close($fh) || die;

       This module provide a constructor method	for Google Chart URLs.	When
       dereferenced Google will	serve back PNG images of charts	based on the
       provided	parameters.

       The Google Chart	service	is described at
       <> and	these pages also define	the
       Web API in terms	of the parameters these	URLs take.  This module	make
       it easier to generate URLs that conform to this API as it automatically
       takes care of data encoding and scaling,	as well	as hiding most of the
       cryptic parameter names that the	API uses in order to generate shorter

       The following constructor method	is provided:

       $uri = URI::GoogleChart->new( $type, $width, $height, %opt )
	   The constructor method's first 3 arguments are mandatory and	they
	   define the type of chart to generate	and the	dimension of the image
	   in pixels.  Additional arguments are	provided as key/value pairs.
	   The return value is an HTTP URI object, which can also be treated
	   as a	string.

	   The $type argument can either be one	of the type code documented at
	   the Google Charts page or one of the	following more readable






	   The additional arguments in the form	of key/value pairs can either
	   be one of the "chXXX" parameters documented on the Google Chart
	   pages or one	of the following:

	   data	=> [{ v	=> [$v1, $v2,...], %opt	}, ...]
	   data	=> [[$v1, $v2,...], [$v1, $v2,...], ...]
	   data	=> [$v1, $v2,...]
	   data	=> $v1
	       The data	to be charted is provided as an	array of data series.
	       In the most general form	each series is defined by a hash with
	       the "v" element being an	array of data points (numbers) in the
	       series.	Missing	data points should be provided as "undef".
	       Other hash elements can be provided to define various
	       properties of the series.  These	are described below.

	       As a short hand when you	don't need to define other properties
	       besides the data	points you can provide an array	of numbers
	       instead of the series hash.

	       As a short hand when you	only have a single data	series,	you
	       can provide a single array of numbers, and finally if you only
	       have a single number you	can provide it without wrapping	it in
	       an array.

	       Data series belong to ranges.  A	range is defined by a minimum
	       and a maximum value.  Data points are scaled so that they are
	       plotted relative	to the range they belong to.  For example if
	       the range is (5 .. 10) then a data point	value of 7.5 is
	       plotted in the middle of	the chart area.	 Ranges	are
	       automatically calculated	based on the data provided, but	you
	       can also	force certain minimum and maximum values to apply.

	       The following data series properties can	be provided in
	       addition	to "v" described above:

	       The "range" property can	be used	to group data series together
	       that belong to the same range.  The value of the	"range"
	       property	is a range name.  Data series without a	"range"
	       property	belong to the default range.

	   min => $num
	   max => $num
	       Defines the default minimum and maximum value for the default
	       range.  If not provided the minimum and maximum is calculated
	       from the	data points belonging to this range.

	       The specified minimum or	maximum	are ignored if some of data
	       values provided are outside this	range.

	       Chart types that	plot relative values (like bar charts or venn
	       diagrams) should	use 0 as the minimum, as this make the
	       relative	size of	the data points	stay the same after scaling.
	       Because of this the default default minimum for these charts is
	       0, so you don't actually	need to	specify	it.

	   range_round => $bool
	       Extend the default range	so that	the min/max values are nice
	       multiples of 1, 5, 10, 50, 100,... and such numbers.  This
	       gives the chart more "air" and look better if you display the
	       range of	values with "range_show".

	   range_show => "left"
	   range_show => "right"
	   range_show => "top"
	   range_show => "bottom"
	       Makes the given axis show the range of values charted for the
	       default range.

	   range => { $name => \%opt, ...},
	       Define parameters for named data	series ranges.	The range
	       named ""	is the default range.

	       The option values that can be set are "min", "max", "round",
	       "show".	See the	description of the corresponding entry for the
	       default range above.

	   encoding => "t"
	   encoding => "s"
	   encoding => "e"
	       Select what kind	of data	encoding you want to be	used.	They
	       differ in the resolution	they provide and in their readability
	       and verbosity.  Resolution matters if you generate big charts.
	       Verbosity matters as some web client might refuse to
	       dereference URLs	that are too long.

	       The "t" (or "text") encoding is the most	readable and verbose.
	       It might	consume	up to 5	bytes per data point. It provide a
	       resolution of 1/1000.

	       The "s" (or "simple") encoding is the most compact; only
	       consuming 1 byte	per data point.	 It provide a resolution of

	       The "e" (or "extended") encoding	provides the most resolution
	       and it consumes 2 bytes per data	point.	It provide a
	       resolution of 1/4096.

	       The default encoding is	automatically selected based on	the
	       resolution of the chart and the number of data points provided.

	   color => $color
	   color => [$color1, $color2, ...]
	       Sets the	colors to use for charting the data series.  The
	       canonical form for $color is hexstrings either of "RRGGBB" or
	       "RRGGBBAA" form.	 When you use this interface you might also
	       use "RGB" form as well as some comon names like "red", "blue",
	       "green",	"white", "black",... which are expanded	to the
	       canonical form in the URL.

	       The built in colors are the 16 colors of	the HTML specification
	       (see <>).  If you
	       want to use additional color names you can assign your mapping
	       to the %URI::GoogleChart::COLOR_ALIAS hash before start
	       creating	charts.	 Example:

		   local $URI::GoogleChart::COLOR_ALIAS{"gold"}	= "FFD700";

	   background => $color
	       Sets the	color for the chart background.	 See description for
	       color above for how to specify color values.  The color value
	       "transparent" gives you a fully transparent background.

	   title => $str
	   title => [ $str, $color, $fontsize ]
	       Sets the	title for the chart; optionally	changing the color and
	       fontsize	used for the title.

	   label = $str
	   label = [ $str, $str,... ]
	       Labels the data (or data	series)	of the chart.

	   rotate => $degrees
	       Rotate the orientation of a pie chart (clockwise).

	       The first slice starts at the right side	of the pie (at 3
	       o'clock).  If you rotate	the pie	90 degrees the first slice
	       starts at the bottom.  If you rotate -90	degrees	(or 270) the
	       first slices starts at the top of the pie.

	   margin => $num
	   margin => [ $left, $right, $top, $bottom ]
	       Sets the	chart margins in pixels.  If a single number is
	       provided	then all the margins are set to	this number of pixels.




       Copyright 2009 Gisle Aas.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2009-08-15		   URI::GoogleChart(3)


Want to link to this manual page? Use this URL:

home | help