PHPGraphlib Remote API

The PHPGraphLib Remote API allows you to create PHPGraphLib graphs without ever having to download the PHPGraphLib library. Instead, you format your request and send it to the API graph generator URI. The API graph generator then creates an image of your requested graph on the PHPGraphLib servers and sends you back the remote location of the created image. Simply include that location in a an html <img> tag to display your graph.

Why Use the Remote API?

  • Portability - Integrate PHPGraphLib graphs no matter what your platform is. PHP is not necessary!
  • Scalability - You won't have to worry about having multiple copies of PHPGraphLib on different instances.
  • Stability - You'll always be using the latest version of PHPGraphLib. No need to upgrade!

Usage Policy

The PHPGraphLib API has the same usage policy as PHPGraphLib - it is free for personal use and requires a small fee for commercial use. For more information, see the Usage Policy.

Getting Started

Constructing Your Request

PHPGraphlib Remote API calls can return data in two different formats, XML and URL (plain text). The XML format allows more useful information to be sent back to you, while the URL plain text format only returns the fully quallifed location of the graph image.

XML Example:

<phpgrahphlib>
  <imagename>98cd6a78c81992f34440a82094b6d748.png</imagename>
  <imagelocation>http://www.ebrueggeman.com/phpgraphlib/api/files/98cd6a78c81992f34440a82094b6d748.png</imagelocation>
  <imagetag>
    <!--[CDATA[<img width="650" height="200" src="http://www.ebrueggeman.com/phpgraphlib/api/files/98cd6a78c81992f34440a82094b6d748.png" /-->]]>
  </imagetag>
  <error></error>
  <version>2.21</version>
</phpgrahphlib>

URL Plain Text Example:

http://www.ebrueggeman.com/phpgraphlib/api/files/98cd6a78c81992f34440a82094b6d748.png

Graph Parameters

To build your graph parameters, construct an object of type stdclass. Just like the library, there are 3 required variables: width, height and data. Syntax is different, but similar, to the regular PHPGraphLib library.

/** Required variables **/
$graph = new stdclass;
$graph->width = 500;
$graph->height = 350;
$graph->data = array(124, 35, 73, 223, 42, 673, 123);

To customize the your request to the API Graph Generator, you assign the name of the PHPGraphLib library function to the object, and pass the normal parameters of the function as the value. If there is more than one parameter passed to the function, you need to assign those values as an array. Also, if the parameter is boolean, you need to assign it with single or double quotes.

/** Functions **/
//instead of:
$graph->setTitle('Seattle Average Temp');
//use this instead:
$graph->setTitle = 'Seattle Average Temp';
 
/** Functions with multiple parameters **/
//instead of:
$graph->setupYAxis(12, "yellow");
//use this instead:
$graph->setupYAxis = array(12, "yellow");
 
/** Boolean parameters **/
//instead of:
$graph->setGrid('false');
//use this instead:
$graph->setGrid = 'false';

Note: not all PHPGraphlib functions are allowed with the API, though *most* are. If you're in doubt, consult the Function Reference for API availability.

Serializing Your Request with JSON

JSON is the preferred method of sending graph parameters to the API graph generator because it is language independent and very lightweight. Using JSON with PHP depends on your version of PHP. If you are using a different programming language than PHP to construct your requests, you'll need to use your language's JSON implementation.

PHP Version JSON Usage
PHP 5.2 + Starting with PHP 5.2.0, the JSON package was bundled with PHP. You can use the json_encode() and json_decode() functions without any further configuration.
PHP 4, PHP 5 To encode data in JSON in versions less than 5.2, you can either install the PECL JSON package, or you can download an stand alone JSON class.

To serialize with JSON, jimply pass your already configured $graph object to the json_encode() function. Next, you'll need to url_encode() your encoded graph data.

/** Serializing with JSON **/
$encoded = urlencode(json_encode($graph));

Serializing Your Request with serialize()

Alternately, you can use PHP's native serialize() function instead of JSON.

/** Serializing with JSON **/
$encoded = urlencode(serialize($graph));

Making the Request and Parsing the Results

You'll need to construct your the request base that you'll be hitting and set query args.

Request Parts
Request Base http://www.ebrueggeman.com/phpgraphlib/api/
Serialized Graph Data g=XXXXX
Output Type type=xml or type=url

There are many ways you can make the request in PHP - simplexml, curl, fopen, file_get_contents, etc. If you're not using PHP, you'll need to find a function that can open a remote URI.

The easiest way is using SimpleXML, which was first available with PHP 5.0.1:

/** PHP 5 Request and Parsing Method **/
$target = 'http://www.ebrueggeman.com/phpgraphlib/api/?g=' . $encoded . '&type=xml';
$xml_object =  new SimpleXMLElement($target, NULL, TRUE);
 
echo 'Image Tag: '. $xml_object->imageTag;
echo 'Errors: '. $xml_object->error;

Alternately, you can use file_get_contents and the XMLParse package is you are using PHP 4.

/** PHP 4.3+ Request and Parsing Method **/
$target = 'http://www.ebrueggeman.com/phpgraphlib/api/?g=' . $encoded . '&type=xml';
$xml_contents = trim(file_get_contents($target));
 
$parser = xml_parser_create();
xml_parse_into_struct($parser, $xml_contents, $vals, $index);
xml_parser_free($p);
 
$xml_values = array();
foreach ($vals as $value_array) {
  if ($value_array['type'] == 'complete') {
    $xml_values[$value_array['tag']] = $value_array['value'];
  }
}
 
//note that xml elements are uppercase here
echo 'Image Tag: '. $xml_values['IMAGETAG'];
echo 'Errors: '. $xml_values['ERROR'];

Full PHPGraphLib Remote API Example

<?php
//setup graph
$graph = new stdclass;
$graph->width = 500;
$graph->height = 350;
$graph->data=array('AL'=>3731, 'MI'=>763, 'NY'=>3245, 'TX'=>4373, 'WA'=>12124, 'WY'=>5535);
$graph->setGradient = array('red', 'maroon');
$graph->setLegend = 'true';
$graph->setLegendTitle = 'Widgets';
$graph->setTitle = 'Widgets Produced Per State';
$graph->setTitleLocation = 'left';
 
//JSON encode graph object
$encoded = urlencode(json_encode($graph));
 
//retrieve XML
$target = 'http://www.ebrueggeman.com/phpgraphlib/api/?g=' . $encoded . '&type=xml';
$xml_object =  new SimpleXMLElement($target, NULL, TRUE);
 
//if there are no errors, display graph
if (empty($xml_object->error)) {
  echo $xml_object->imageTag;
}
else {
  echo 'There was an error generating the graph: '. $xml_object->error;
}
?>

This is the resulting graph: