ZingChart Hosted Web Service

Web Service URLs: http://api.zingchart.com, http://hosted.zingchart.com

Table Of Contents

OverviewTOP

ZingChart provides a number of APIs for easier and customized charting. This document covers our Web services API useful for hosting and generating charts remotely. Documentation on the interactive client-side API and associated event model is found at URL and URL.

ZingChart provides two approaches for using the Web Services API:

The API for each is primarily the same except for whether any generated site is stored with a unique key (zingid) or not.

The ZingChart API can be used for freely in personal use mode for hosting and generating charts on non-commercial or personal sites. Developers may also use the API freely for development purposes on commercial sites with registration and approval. All free accounts will include a brand watermark and be subject to rate and view limits (See Free account limits)

High volume and commercial usage requires a paid developer API key. Paid access will allow for larger numbers of chart views, removal of branding, full API access, and full support. Plans can be purchased on monthly or yearly basis (See Paid API plans). Bundles with standard ZingChart licenses are also available, contact sales for more information.

Method: putTOP

URL: http://api.zingchart.com/put
HTTP Methods: GET, POST
Protocols: http
Description: Returns a zingid for a passed valid ZingChart packet.
Request
Parameter Short Definition & Sample Values Description
data* d* STRING
{"graphset" : [{"type" : "line",
"series" : [{"values" : [16,12,8
,7,6,11,12,11,14,9]}]}]}
The chart's JSON description. Watch for size limitations with GETs.
zingid zid STRING
4d387a7ded5a7
ZingId of the record being updated. Both ZingId and LockCode have to be supplied in order to perform an update via PUT. This does not apply for the clients that use API Keys as an identification token.
lockcode lc STRING
4f422c01aeb286354d290d756229f069
LockCode of the record being updated. Both ZingId and LockCode have to be supplied in order to perform an update via PUT. This does not apply for the clients that use API Keys as an identification token.
fileurl furl STRING
http://www.domain.com/datasource/sales.json
Specifies a URL to hold the JSON packet. Remote URLs are only allowed with licensed API calls.
width w INTEGER
(10-1000)
480
Width of the saved ZingChart.
height h INTEGER
(10-1000)
320
Height of the saved ZingChart.
imageformat if STRING
(gif | jpg | [png] | tiff)
jpg
Format of a chart image.
imagequality iq INTEGER
(10-100)
80
Specifies the quality of the image for compression purposes.
key k STRING
dd413d8b3fb3f947d8e8ca72d9eee5d6
Valid API Key. Identifies the API client.
output o STRING
(img | flash | html5 | pdf | svg | vml | canvas)
img
Defines the output format for the saved ZingChart.
wmtype wt INTEGER
([1] | 2)
2
Defines the type of watermark to use on the chart when not used with a valid API Key.
wmposition wp STRING
(top-right | tr | top-left | tl | [bottom-right] | br | bottom-left | bl)
tr
Defines the position of the branding watermark.
filename fn STRING
sales.pdf
Specifies the name of the file to save an output to, only works for static or PDF renders.
encoding enc STRING
([binary] | base64)
base64
Encoding method for the returned data.
Response (JSON format)
Attribute Definition & Sample Values Description
result INTEGER
(0=error | 1=success)
1
Specifies method's completion status.
error STRING
(''=success)
Invalid Zing Id
Error description.
errorcode INTEGER
1000
Error code. View list of Error Codes
zingid STRING
4d387a7ded5a7
Allocated ZingId.
lockcode STRING
4f422c01aeb286354d290d756229f069
LockCode, required for future PUTs on same ZingId location (data updates).

Method: getTOP

URL: http://api.zingchart.com/get
HTTP Methods: GET, POST
Protocols: http
Description: Returns data & chart definitions for a passed valid ZingId.
Request
Parameter Short Definition & Sample Values Description
zingid* zid* STRING
4d387a7ded5a7
ZingId of the record being queried. Both ZingId and API Key have to be supplied in order to perform the GET method for the clients that use API Keys as an identification token.
key k STRING
dd413d8b3fb3f947d8e8ca72d9eee5d6
Valid API Key. Identifies the API client.
Response (JSON format)
Attribute Definition & Sample Values Description
result INTEGER
(0=error | 1=success)
1
Specifies method's completion status.
error STRING
(''=success)
Invalid Zing Id
Error description.
errorcode INTEGER
1000
Error code. View list of Error Codes
data STRING
{"graphset" : [{"type" : "line",
"series" : [{"values" : [16,12,8
,7,6,11,12,11,14,9]}]}]}
The chart's JSON description.
fileurl STRING
http://www.domain.com/datasource/sales.json
URL of the JSON packet. Remote URLs are only allowed with licensed API calls.
width INTEGER
(10-1000)
480
Width of the saved ZingChart.
height INTEGER
(10-1000)
320
Height of the saved ZingChart.
imageformat STRING
(gif | jpg | [png] | tiff)
jpg
Format of a chart image.
imagequality INTEGER
(10-100)
80
Specifies the quality of the image for compression purposes.
output STRING
(img | flash | html5 | pdf | svg | vml | canvas)
img
Output of the saved ZingChart.
wmtype INTEGER
([1] | 2)
2
Type of watermark to use on the saved ZingChart.
wmposition STRING
(top-right | tr | top-left | tl | [bottom-right] | br | bottom-left | bl)
tr
Position of the branding watermark.
filename STRING
sales.pdf
Specifies the name of the file to save an output to, only works for static or PDF renders.
encoding STRING
([binary] | base64)
base64
Encoding method for the returned data.

Method: render (view)TOP

URL: http://api.zingchart.com/render, http://api.zingchart.com/view & aliases (see output parameter)
HTTP Methods: GET, POST
Protocols: http
Description: Renders a ZingChart according to output definitions.
Request
Parameter Short Definition & Sample Values Description
data d STRING
(URL encoded)
%7B%22graphset%22+...5D%7D
(encoded version of)
{"graphset" : [{"type" : "line",
"series" : [{"values" : [16,12,8
,7,6,11,12,11,14,9]}]}]}
The chart's JSON description. Watch for size limitations with GETs.
zingid zid STRING
4d387a7ded5a7
ZingId of the record being rendered.
fileurl furl STRING
http://www.domain.com/datasource/sales.json
Specifies a URL to hold the JSON packet. Remote URLs are only allowed with licensed API calls.
width w INTEGER
(10-1000)
480
Width of the rendered ZingChart.
height h INTEGER
(10-1000)
320
Height of the rendered ZingChart.
imageformat if STRING
(gif | jpg | [png] | tiff)
jpg
Format of the rendered image.
imagequality iq INTEGER
(10-100)
80
Specifies the quality of the rendered image.
key k STRING
dd413d8b3fb3f947d8e8ca72d9eee5d6
Valid API Key. Identifies the API client.
output o STRING
(img | flash | html5 | pdf | svg | vml | canvas)
img
Defines the output format for the rendered ZingChart. You can avoid passing that parameter using a URL alias:
  • http://api.zingchart.com/img
  • http://api.zingchart.com/pdf
  • http://api.zingchart.com/flash
  • http://api.zingchart.com/canvas
  • http://api.zingchart.com/svg
  • http://api.zingchart.com/vml
  • http://api.zingchart.com/html5
wmtype wt INTEGER
([1] | 2)
2
Defines the type of watermark to use on the rendered chart when not used with a valid API Key.
wmposition wp STRING
(top-right | tr | top-left | tl | [bottom-right] | br | bottom-left | bl)
tr
Defines the position of the branding watermark.
filename fn STRING
sales.pdf
Specifies the name of the file to save an output to, only works for static or PDF renders.
encoding enc STRING
([binary] | base64)
base64
Encoding method for the returned data.
Response (JSON format, if error)
Attribute Definition & Sample Values Description
result INTEGER
(0=error)
0
Specifies method's completion status.
error STRING
Invalid Zing Id
Error description.
errorcode INTEGER
1000
Error code. View list of Error Codes

Error CodesTOP

Error Code Error Message
1000 Invalid Zing Id
1001 Invalid API Key
1002 Invalid Data
1003 Invalid IP
1004 Invalid Lock Code
1005 Invalid Client
2000 PUT Operation Not Ready
2001 PUT Daily Quota Exceeded
2002 PUT Weekly Quota Exceeded
2003 PUT Monthly Quota Exceeded
2004 PUT Total Quota Exceeded
2101 GET Daily Quota Exceeded
2102 GET Weekly Quota Exceeded
2103 GET Monthly Quota Exceeded
2104 GET Total Quota Exceeded
2201 RENDER Daily Quota Exceeded
2202 RENDER Weekly Quota Exceeded
2203 RENDER Monthly Quota Exceeded
2204 RENDER Total Quota Exceeded
3000 PUT Operation Not Ready
3001 PUT Total Quota Exceeded
3002 Storage Quota Exceeded
9000 Zing Id Locked

Service RestrictionsTOP

Both API Key authenticated clients and public users have to follow several rules in order to use the ZingChart Hosted Web Service:

API Key authenticated clients

RENDER* - means a non-cached RENDER operation (if data or any other parameter on a ZingId storage has not been changed between two RENDER calls)

Public users

RENDER* - means a non-cached RENDER operation (if data or any other parameter on a ZingId storage has not been changed between two RENDER calls)

Tutorial: Static image generationTOP

Consider a ZingChart JSON definition of a basic chart:

	{
		"graphset" : [
			{
				"type" : "line",
				"series" : [
					{
						"values" : [16,12,8,7,6,11,12,11,14,9]
					}
				]
			}
		]
	}
	

its urlencoded version is:

%7B%22graphset%22+%3A+%5B%7B%22type%22+%3A+%22line%22%2C%22series%22+%3A+%5B%7B%22values%22+%3A+%5B16%2C12%2C8%2C7%2C6%2C11%2C12%2C11%2C14%2C9%5D%7D%5D%7D%5D%7D

so in order to render a png file using ZingChart hosting service in the HTML code, one must add the following code:

<img src="http://api.zingchart.com/img?d=%7B%22graphset%22+%3A+%5B%7B%22type%22+%3A+%22line%22%2C%22series%22+%3A+%5B%7B%22values%22+%3A+%5B16%2C12%2C8%2C7%2C6%2C11%2C12%2C11%2C14%2C9%5D%7D%5D%7D%5D%7D" />

and the result is (using the service's defaults parameters):

With some parameters, the generated ressource can be customized. In the following example we change width and height, we tell the service to provide us a low quality jpeg file:

<img src="http://api.zingchart.com/img?if=jpg&iq=30&w=600&h=160&d=%7B%22graphset%22+%3A+%5B%7B%22type%22+%3A+%22line%22%2C%22series%22+%3A+%5B%7B%22values%22+%3A+%5B16%2C12%2C8%2C7%2C6%2C11%2C12%2C11%2C14%2C9%5D%7D%5D%7D%5D%7D" />

and the result is:

Tutorial: Create a downloadable PDF fileTOP

Consider a ZingChart JSON definition of a basic chart:

	{
		"graphset" : [
			{
				"type" : "line",
				"series" : [
					{
						"values" : [16,12,8,7,6,11,12,11,14,9]
					}
				]
			}
		]
	}
	

its urlencoded version is:

%7B%22graphset%22+%3A+%5B%7B%22type%22+%3A+%22line%22%2C%22series%22+%3A+%5B%7B%22values%22+%3A+%5B16%2C12%2C8%2C7%2C6%2C11%2C12%2C11%2C14%2C9%5D%7D%5D%7D%5D%7D

In order to create a link to this chart rendered in a pdf file, in the HTML code one needs to add:

<a href="http://api.zingchart.com/pdf?fn=mychart.pdf&d=%7B%22graphset%22+%3A+%5B%7B%22type%22+%3A+%22line%22%2C%22series%22+%3A+%5B%7B%22values%22+%3A+%5B16%2C12%2C8%2C7%2C6%2C11%2C12%2C11%2C14%2C9%5D%7D%5D%7D%5D%7D">Download PDF</a>

and the result is (using the service's defaults parameters):

Download PDF

Tutorial: Using API methodsTOP

Getting a ZingId storage space

URL: http://api.zingchart.com/put
HTTP Method: POST
POST Parameter Sample Value
key dd413d8b3fb3f947d8e8ca72d9eee5d6 (only for clients that use the API Key as identification method)
data { "graphset" : [ { "type" : "line", "series" : [ { "values" : [ 16, 12, 8, 7, 6, 11, 12, 11, 14, 9 ] } ] } ] }
imageformat jpg
imagequality 80
Sample Response
{
	"result":1,
	"error":"",
	"zingid":"4d4c1dd811c03",
	"lockcode":"8095318e34e546d070b470031887a814"
}

Updating a ZingId storage space

URL: http://api.zingchart.com/put
HTTP Method: POST
POST Parameter Sample Value
zingid 4d4c1dd811c03
key dd413d8b3fb3f947d8e8ca72d9eee5d6 (only for clients that use the API Key as identification method)
lockcode 8095318e34e546d070b470031887a814 (only for clients that don't use the API Key as identification method)
data { "graphset" : [ { "type" : "bar", "series" : [ { "values" : [ 116, 112, 88, 87, 86, 111, 112, 111, 114, 89 ] } ] } ] }
imageformat png
imagequality 100
Sample Response
{
	"result":1,
	"error":"",
	"zingid":"4d4c1dd811c03",
	"lockcode":"8095318e34e546d070b470031887a814"
}

Retrieving information from a ZingId storage space

URL: http://api.zingchart.com/get
HTTP Method: POST
POST Parameter Sample Value
zingid 4d4c1dd811c03
key dd413d8b3fb3f947d8e8ca72d9eee5d6 (only for clients that use the API Key as identification method)
Sample Response
{
	"result":1,
	"error":"",
	"data":"{ \"graphset\" : [ { \"type\" : \"bar\", \"series\" : [
				{ \"values\" : [ 116, 112, 88, 87, 86, 111, 112, 111, 114, 89 ] }
			] } ] }",
	"width":"0",
	"height":"0",
	"provider":"",
	"imageformat":"png",
	"imagequality":"100",
	"wmtype":"0",
	"wmposition":"",
	"output":"",
	"fileurl":"",
	"encoding":"",
	"filename":""
}

Rendering a chart from a ZingId storage space

Image in a web page

<img src="http://api.zingchart.com/img?zingid=4d4c1dd811c03" />

or

<img src="http://api.zingchart.com/img?zingid=4d4c1dd811c03&key=dd413d8b3fb3f947d8e8ca72d9eee5d6" />

Note: Clients that identify with an API Key should use this method only in a company intranet or on other private space.

Note: Other parameters can be added in the query string in order to enforce rendering type/output. For example, even if on PUT operations we specified imageformat = PNG and imagequality = 100, the following URL renders a low quality JPG of the chart:

<img src="http://api.zingchart.com/img?zingid=4d4c1dd811c03&imageformat=jpg&imagequality=40" />

Link to a downloadable image or pdf

<a href="http://api.zingchart.com/img?zingid=4d4c1dd811c03&filename=mychart.png">Download Image</a>

or

<a href="http://api.zingchart.com/pdf?zingid=4d4c1dd811c03&filename=mychart.pdf">Download PDF</a>

Render the dynamic version of a chart

<script type="text/javascript" src="http://api.zingchart.com/html5?zingid=4d4c1dd811c03"></script>

or

<script type="text/javascript" src="http://api.zingchart.com/flash?zingid=4d4c1dd811c03"></script>

A PHP basic example of a batch operation
<?php

// the script assumes you use a helper class for HTTP requests, code for your version may vary
require_once 'HttpRequest.php';

// open a zingid storage
$oRequest = new HttpRequest('http://api.zingchart.com/put', 'POST', array('data' => '{}'));
$sResponse = $oRequest->getContent();
$aResponse = json_decode($sResponse);

if ($aResponse->result == 1) {
	// save the zingid & lock code for future use
	$sZingId = $aResponse->zingid;
	$sLockCode = $aResponse->lockcode;

	$sDataTemplate = '{ "graphset" : [ { "type" : "bar", "title" : { "text" : "Chart No. %chartno%" },
		"series" : [ { "values" : [ %values% ] } ] } ] }';

	for ($i=0;$i<20;$i++) {
		// create a random data set (this can be easily adopted to read
		// from a database or any other dynamic source)
		$sValues = '';
		for ($j=0;$j<12;$j++) {
			$sValues .= rand(10, 20) . ',';
		}
		$sValues = substr($sValues, 0, -1);
		$sData = str_replace(array('%chartno%', '%values%'), array($i, $sValues), $sDataTemplate);

		// wait for the next PUT operation to become available otherwise you get an error
		sleep(2);

		// update the zingid storage with the new data
		$aData = array(
			'zingid' => $sZingId,
			'lockcode' => $sLockCode,
			'data' => $sData
		);
		$oRequest = new HttpRequest('http://api.zingchart.com/put', 'POST', $aData);
		$sResponse = $oRequest->getContent();
		$aResponse = json_decode($sResponse);

		if ($aResponse->result == 1) {
			// get the chart representation as a png image
			$aData = array(
				'zingid' => $sZingId
			);
			$oRequest = new HttpRequest('http://api.zingchart.com/render', 'POST', $aData);
			$sResponse = $oRequest->getContent();

			// save it on disk (other uses can be imagined here: sending it
			// in an email, creating a report with it, etc)
			file_put_contents('/tmp/file' . $i . '.png', $sResponse);
		}

	}
}

?>