Getting started

Making requests

The ChartBlocks API is hosted at https://api.chartblocks.com/v1/. The API is REST based, providing access to chart, set, data and user information.

To generate charts on-the-fly, please see the Image API.

SDK’s

To get you up and running with the API as quickly as possible we’ve implemented an SDK for PHP. Other languages will be available shortly.

Authorization

The majority of API calls must be made as an authorized user. An ACCESS_TOKEN and SECRET_KEY can be generated from your ChartBlocks profile page. Together these are used to sign requests.

Authorizing a request

We’d suggest using one our pre-built SDKs if you’re new to development, but to authenticate requests in your own clients, please read on.

Your SECRET_KEY is never sent in the request, only the ACCESS_TOKEN. The SECRET_KEY is used to generate a SIGNATURE which both authenticates the request as coming from you, and mitigates man in the middle attacks.

The signature is sent in your HTTP request using the Authorization header in the format:

'Authorization: BASIC ' . base64_encode(ACCESS_TOKEN . ':' . SIGNATURE);

Generating a signature

This snippet of psuedo code describes how to generate a signature. It should be possible to implement this in your language of choice.

var key1 = sha1(body);
var key2 = key1 . SECRET_KEY;
var key3 = sha1(key2);
var signature = base64_encode(key3);

The body variable is your request body. For a GET request this would be your query parameters in the format:

param1=val&param2=val

For POST, PUT and PATCH requests this would be your request body, normally a JSON document, i.e.:

{
  "name": "My Chart",
  "isPublic": true
}

The SECRET_KEY is obtained along with the ACCESS_TOKEN from the profile page of your ChartBlocks account.

Item tokens

Charts and datasets can are assigned a token, allowing people without a ChartBlocks account to view private items providing they know the token.

To request a chart or set with a token, pass the given token as a GET parameter of t, i.e.

https://api.chartblocks.com/v1/chart/541fdd38c9a61d68707f9d86?t=c9ea94ad

Chart config

The chart config object can end up rather large, and contains enough parameters to warrant its own documentation page. Please reference the Chart Config documentation separately for more information on how to format your config object.

Resources

Chart

Chart objects contain all the information required to render a chart, along with meta information on the owner.

Create

POST
https://api.chartblocks.com/v1/chart
Parameters
Parameter Type Description
name String

A reference for the chart
isPublic Boolean

Whether the chart can be viewed in the public gallery

Default: true

config Object

The chart config (see Chart Config docs)
Success example
            HTTP/1.1 200 OK
{
 "chart": {
   .. chart object ..
 }
}

Delete

DELETE
https://api.chartblocks.com/v1/chart/:id

Get

GET
https://api.chartblocks.com/v1/chart/:id
Parameters
Parameter Type Description
t String

Token to view chart if isn't public
Success example
            HTTP/1.1 200 OK
{
 "chart": {
   "id": "541fdd38c9a61d68707f9d86",
   "name": "My chart",
   "tags": [ "example", "bar" ],
   "config": {
     .. config object ..
   },
   "isPublic": true,
   "totalViews": 153,
   "createdAt": "2014-09-22T09:26:32+00:00",
   "updatedAt": "2014-09-22T09:29:57+00:00",
   "publicUrl": "http://public.chartblocks.com/c/541fdd38c9a61d68707f9d86",
   "versionHash": "4ee3b408",
   "images": {
     "png": { "name": "PNG", "extension": "png", "url": "https://img.chartblocks.com/541fdd38c9a61d68707f9d86.png"},
     "pdf": { "name":"PDF", "extension": "pdf", "url": "https://img.chartblocks.com/541fdd38c9a61d68707f9d86.pdf"},
     "svg": { "name":"SVG", "extension": "svg", "url": "https://img.chartblocks.com/541fdd38c9a61d68707f9d86.svg"},
     "eps": { "name":"EPS", "extension": "eps", "url": "https://img.chartblocks.com/541fdd38c9a61d68707f9d86.eps"},
     "ps": { "name":"PS", "extension": "ps", "url": "https://img.chartblocks.com/541fdd38c9a61d68707f9d86.ps"}
   },
   "creator": {
     .. user object ..
   },
   "editable": false
 }
}

List

GET
https://api.chartblocks.com/v1/chart
Parameters
Parameter Type Description
public Boolean

Show all public charts (defaults to own charts).

Default: false

sort_by String

Sort results by given field.

Valid values: updatedAt createdAt name totalViews

Default: updatedAt

order String

Order of results

Valid values: asc desc

Default: asc

limit Number

Maximum number of results to return per request

Default: 50

page Number

Which page of results to return (coupled with limit for pagination)

Default: 1

term String

Search query
creator String

Filter results to a particular user (used with 'public' to get a users public charts)
Success example
            HTTP/1.1 200 OK
{
 "charts": [
   { .. chart object .. },
   { .. chart object .. }
 ],
 "state": {
   "totalRecords": 2
 }
}

Patch

PATCH
https://api.chartblocks.com/v1/chart/:id

All paramters are optional and get merged against existing values server side

Parameters
Parameter Type Description
name String

A reference for the chart
isPublic Boolean

Whether the chart can be viewed in the public gallery

Default: true

config Object

The chart config (see Chart Config docs)
Success example
            HTTP/1.1 200 OK
{
 "chart": {
   .. chart object ..
 }
}

Update

PUT
https://api.chartblocks.com/v1/chart/:id
Parameters
Parameter Type Description
name String

A reference for the chart
isPublic Boolean

Whether the chart can be viewed in the public gallery

Default: true

config Object

The chart config (see Chart Config docs)
Success example
            HTTP/1.1 200 OK
{
 "chart": {
   .. chart object ..
 }
}

Data

Alter data structure

PUT
https://api.chartblocks.com/v1/data/alter/:set-id
Parameters
Parameter Type Description
method String

The type of change

Valid values: shiftRow shiftCol
index Number

Row/column to shift from
Number Number

of row/columns to shift by
Success example
            HTTP/1.1 200 OK
{
   "success": true
}

Append data

PUT
https://api.chartblocks.com/v1/data/append/:set-id
Parameters
Parameter Type Description
data Object

The data array to append to the bottom of the set, consists of an array of objects keyed by column ID
Success example
            HTTP/1.1 200 OK
{
   "success": true
}

Get data

GET
https://api.chartblocks.com/v1/data/:set-id
Parameters
Parameter Type Description
version Number

Which version of the data would you like?

Default: live

limit Number

How many rows to return?

Default: 100

offset Number

Returns from starting at offset

Default: 0

fromRow Number

As missing rows are ommitted from results, allows you to select a range of rows specifically

Default: 1

toRow Number

As missing rows are omitted from results, allows you to select a range of rows specifically
Success example
            HTTP/1.1 200 OK
{
   "data": {
       "1": {
           "cells": {
               "1": {
                   "t": "s",
                   "o": null,
                   "c": 1,
                   "v": "Year"
               },
               "2": {
                   "t": "s",
                   "o": null,
                   "c": 2,
                   "v": "Facebook"
               },
               "3": {
                   "t": "s",
                   "o": null,
                   "c": 3,
                   "v": "Twitter"
               },
               "4": {
                   "t": "s",
                   "o": null,
                   "c": 4,
                   "v": "Pinterest"
               }
           }
       },
       "2": {
           "cells": {
               "1": {
                   "t": "i",
                   "o": "2011",
                   "c": 1,
                   "v": 2011
               },
               "2": {
                   "t": "i",
                   "o": "845000000",
                   "c": 2,
                   "v": 845000000
               },
               "3": {
                   "t": "i",
                   "o": "300000000",
                   "c": 3,
                   "v": 300000000
               }
           }
       }
   },
   "meta": {
       .. meta object ..
   },
   "query": {
       "setId": "53edd85d279871ba098b4587",
       "version": 1,
       "fromRow": 1,
       "toRow": 50,
       "onlyRows": [],
       "offset": 0,
       "limit": 51,
       "columns": [],
       "groupBy": [],
       "sortBy": [],
       "order": 1,
       "transpose": false
   },
}

Meta

GET
https://api.chartblocks.com/v1/meta/:set-id
Parameters
Parameter Type Description
version Number

Which version of the data would you like meta for?

Default: latest

Success example
            HTTP/1.1 200 OK
{
 "meta": {
   "version": 1,
   "type": 1,
   "rows": 0,
   "columns": 0,
   "createdAt": "2014-09-22T15:57:54+01:00",
   "updatedAt": "2014-09-22T15:57:54+01:00",
   "isImporting": true
 }
}

Save data

PUT
https://api.chartblocks.com/v1/data/:set-id
Parameters
Parameter Type Description
data Object

The data object to update, can be a complete set or partial, keyed by row ID and column ID
Success example
            HTTP/1.1 200 OK
{
   "success": true
}

Truncate data

DELETE
https://api.chartblocks.com/v1/data/:set-id
Success example
            HTTP/1.1 200 OK
{
   "success": true
}

Import

Import data (to new set)

POST
https://api.chartblocks.com/v1/set/import
Parameters
Parameter Type Description
name String

A reference for the set
sourceName String

The type of import

Valid values: blank csv excel
sourceOptions ObjCreateect

Some sources have options (see Import docs) to configure the import process
Success example
            HTTP/1.1 200 OK
{
 "set": {
   .. set object ..
 }
}

Import data (to existing set)

PUT
https://api.chartblocks.com/v1/set/import/:set-id
Parameters
Parameter Type Description
sourceName String

The type of import

Valid values: blank csv excel
sourceOptions ObjCreateect

Some sources have options (see Import docs) to configure the import process
name String

A reference for the set
Success example
            HTTP/1.1 200 OK
{
 "set": {
   .. set object ..
 }
}

Preview start

GET
https://api.chartblocks.com/v1/set/preview
Parameters
Parameter Type Description
sourceName String

The type of import

Valid values: blank csv excel
sourceOptions Object

Some sources have options (see Import docs) to configure the import process
Success example
            HTTP/1.1 200 OK
{
 "preview": {
   "status": "pending",
   "importTaskId": "53f22fe0c9a61d1a55942613",
   "setId": "53f3a6eec9a61de66c942613"
 }
}

Preview status

GET
https://api.chartblocks.com/v1/set/preview/:task-id
Success example
            HTTP/1.1 200 OK
{
 "preview": {
   "status": "pending",
   "importTaskId": "53f22fe0c9a61d1a55942613",
   "setId": "53f3a6eec9a61de66c942613",
   "formOptions": { .. options .. }
 }
}

Set

Create

POST
https://api.chartblocks.com/v1/set
Parameters
Parameter Type Description
name String

A reference for the set
sourceName String

The type of import

Valid values: blank csv excel
sourceOptions Object

Some sources have options (see Import docs) to configure the import process
Success example
            HTTP/1.1 200 OK
{
 "set": {
   .. set object ..
 }
}

Delete

DELETE
https://api.chartblocks.com/v1/set/:id

Get

GET
https://api.chartblocks.com/v1/set/:id
Parameters
Parameter Type Description
t String

Token to view set if isn't public
Success example
            HTTP/1.1 200 OK
{
 "set": {
   "id": "542038f2279871600e8b4567",
   "name": "My test set",
   "tags": [],
   "sourceName": "blank",
   "sourceOptions": null,
   "storeName": "mongo",
   "storeOptions": null,
   "isRemoteStore": false,
   "isPreview": false,
   "isPublic": false,
   "isSample": false,
   "latestVersionNumber": 1,
   "liveVersionNumber": 1,
   "createdAt": "2014-09-22T15:57:54+01:00",
   "updatedAt": "2014-09-22T15:57:54+01:00",
   "editable": true,
   "versions": [
     {
       "version": 1,
       "type": 1,
       "rows": 0,
       "columns": 0,
       "createdAt": "2014-09-22T15:57:54+01:00",
       "updatedAt": "2014-09-22T15:57:54+01:00",
       "isImporting": true
     }
   ]
 }
}

List

GET
https://api.chartblocks.com/v1/set
Parameters
Parameter Type Description
sort_by String

Sort results by given field.

Valid values: updatedAt createdAt name

Default: updatedAt

order String

Order of results

Valid values: asc desc

Default: asc

limit Number

Maximum number of results to return per request

Default: 50

page Number

Which page of results to return (coupled with limit for pagination)

Default: 1

term String

Search query
Success example
            HTTP/1.1 200 OK
{
 "sets": [
   { .. set object .. },
   { .. set object .. }
 ],
 "state": {
   "totalRecords": 2
 }
}

Patch

PATCH
https://api.chartblocks.com/v1/set/:id

All paramters are optional and get merged against existing values server side

Parameters
Parameter Type Description
name String

A reference for the set
Success example
            HTTP/1.1 200 OK
{
 "set": {
   .. set object ..
 }
}

Update

PUT
https://api.chartblocks.com/v1/set/:id
Parameters
Parameter Type Description
name String

A reference for the set
Success example
            HTTP/1.1 200 OK
{
 "set": {
   .. set object ..
 }
}

Template

Get

GET
https://api.chartblocks.com/v1/chart/template/:id
Success example
            HTTP/1.1 200 OK
{
 "chartTemplate": {
   "id": "542038f2279871600e8b4567",
   "name": "My template",
   "templateKey": "my-template",
   "type": "bar",
   "listOrder": 50,
   "isPublic": true,
   "config": { .. template config .. }
   "createdAt": "2014-09-22T15:57:54+01:00",
   "updatedAt": "2014-09-22T15:57:54+01:00"
 }
}

List

GET
https://api.chartblocks.com/v1/chart/template
Parameters
Parameter Type Description
type String

Return templates for particular type.

Valid values: bar line pie area

Default: all

sort_by String

Sort results by given field.

Valid values: updatedAt createdAt name order

Default: name

order String

Order of results

Valid values: asc desc

Default: asc

limit Number

Maximum number of results to return per request

Default: 50

page Number

Which page of results to return (coupled with limit for pagination)

Default: 1

term String

Search query
Success example
            HTTP/1.1 200 OK
{
 "chartTemplates": [
   { .. template object .. },
   { .. template object .. }
 ],
 "state": {
   "totalRecords": 2
 }
}