ZingChart Hosted Web Service

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:

A create and store model that will store chart information and render online
A generative model useful to retrieve charts programmatically

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

per client limitation on the number of operations (PUT/GET/RENDER*) allowed per DAY/WEEK/MONTH, depending on the hosting plan purchased.
per client requirement for the minimum delay required between two successive operations of same type, depending on the hosting plan purchased. Default settings are: 100ms for GET, 200ms for PUT, 400ms for RENDER*.
key parameter (the allocated API Key) is required for all the operations.
IPs/IP ranges filters may be applied, depending on the hosting plan purchased.

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

per ZingId storage limitation on the number of PUT operations allowed (currently 128).
per IP limitation on the maximum number of ZingId storages allowed (currently 16).
lockcode parameter is required for all the PUT operations representing data updates.
per IP requirement for the minimum delay required between two successive operations (currently 2000ms, not applicable on RENDER*)

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:

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:

and the result is:

Tutorial: Create a downloadable PDF fileTOP

Tutorial: Using API methodsTOP

Getting a ZingId storage space

POST Parameter	Sample Value
URL: `http://api.zingchart.com/put`
HTTP Method: `POST`
`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

POST Parameter	Sample Value
URL: `http://api.zingchart.com/put`
HTTP Method: `POST`
`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

POST Parameter	Sample Value
URL: `http://api.zingchart.com/get`
HTTP Method: `POST`
`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

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:

Link to a downloadable image or pdf

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

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

Render the dynamic version of a chart

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

	}
}

?>

ZingChart Hosted Web Service

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

Table Of Contents

OverviewTOP

Method: `put`TOP

Method: `get`TOP

Method: `render` (`view`)TOP

Error CodesTOP

Service RestrictionsTOP

Tutorial: Static image generationTOP

Tutorial: Create a downloadable PDF fileTOP

Tutorial: Using API methodsTOP

Getting a ZingId storage space

Updating a ZingId storage space

Retrieving information from a ZingId storage space

Rendering a chart from a ZingId storage space

Image in a web page

Link to a downloadable image or pdf

Render the dynamic version of a chart

A PHP basic example of a batch operation

ZingChart Hosted Web Service

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

Table Of Contents

OverviewTOP

Method: putTOP

Method: getTOP

Method: render (view)TOP

Error CodesTOP

Service RestrictionsTOP

Tutorial: Static image generationTOP

Tutorial: Create a downloadable PDF fileTOP

Tutorial: Using API methodsTOP

Getting a ZingId storage space

Updating a ZingId storage space

Retrieving information from a ZingId storage space

Rendering a chart from a ZingId storage space

Image in a web page

Link to a downloadable image or pdf

Render the dynamic version of a chart

A PHP basic example of a batch operation

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

Method: `put`TOP

Method: `get`TOP

Method: `render` (`view`)TOP