Getting Started

Welcome to Charts Factory API Documentation. Charts Factory API is very simple and easy to use. Documentation is prepared for you to easily create charts and use them in your application.

Charts Factory API returns a url of a .png image, and you can use it wherever you need.

Currently available chart types are bar, horizontal bar, line, area, pie, doughnut, funnel and pyramid charts. We want to add new chart types soon, if you want to create some other chart type via API, please contact us!

You can also select between 14 themes, named after greek mythological figures!

API BASE URL

https://chartsfactory.com/api/v1/

API URL

https://chartsfactory.com/api/v1/chart/create

API Reference

Charts Factory API is organized around REST. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Charts Factory API accepts POST request, the other request types will fail!

It's a simple and easy to understand API, let's start with Authentication

Authentication

Charts Factory API uses Basic Authentication. You can use Basic Authentication to access the Charts Factory API. With Basic Authentication, you pass your credentials (your Charts Factory account's email address and api key) in each request to the Charts Factory API.

You can pass your credentials as a Base64-encoded header.

Authorization Example
Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo
Authorization Example with PHP
$credentials = base64_encode("your_email_address_here:your_api_key_here");
$config = [
    'headers' => [
        'authorization' => 'Basic ' . $credentials,
        'Content-Type' => 'application/json'
    ]
];
API Key

Once you signed up, you will get an API Key via your email. You can also display your API Key on profile settings page after you logged in to Charts Factory panel.

Data Types

There are 8 request parameters in total on Charts Factory API.

Data Types of each parameters will be described below.

theme : string | required

Defines the theme of chart.

theme parameter requires string. Passing other data types to theme parameter will throw an error.

theme parameter is required, you should always pass theme parameter while making an API call.

Available values for theme parameter are 'hera', 'zeus', 'hades', 'aphrodite', 'ares', 'demeter', 'poseidon', 'hypnos', 'iris', 'artemis', 'athena', 'apollo', 'nemesis', 'hermes'.

type : string | required

Defines the type of chart.

type parameter requires string. Passing other data types to theme parameter will throw an error.

type parameter is required, you should always pass type parameter while making an API call.

Available values for type parameter are 'bar', 'horizontalBar', 'line', 'area', 'pie', 'doughnut', 'funnel', 'pyramid'.

title : string | required

Defines the title of chart.

title parameter requires string. Passing other data types to title parameter will throw an error.

title parameter is required, you should always pass title parameter while making an API call.

label : string | required

Defines the label of chart.

label parameter requires string. Passing other data types to label parameter will throw an error.

label parameter is required, you should always pass label parameter while making an API call.

color : string | optional

Defines the color of chart.

color parameter requires string. Passing other data types to color parameter will throw an error.

color parameter is 7 characters long hexadecimal color. It should start with # For example; "#c23531"

color parameter is optional. If you don't pass color parameter, #5470c6 will be the color of your chart by default.

Also Pie, Doughnut, Funnel and Pyramid charts don't require color parameter, so you don't need to pass it while making an API call for these chart types.

chart_labels : array | required

Defines the labels of data points of chart.

chart_labels parameter requires array. Passing other data types to chart_labels parameter will throw an error.

chart_labels parameter is required, you should always pass chart_labels parameter while making an API call.

chart_data : array | required

Defines the data points of chart.

chart_data parameter requires array. Passing other data types to chart_data parameter will throw an error.

chart_data parameter is required, you should always pass chart_data parameter while making an API call.

Important Note:

chart_data parameter should have name and value keys in array while sending request for pie, doughnut, funnel and pyramid charts! You can see the example requests for those chart types to learn how to use it.

show_data_labels : integer | optional

Defines whether data points of chart will be displayed or not.

show_data_labels parameter requires integer. Passing other data types to show_data_labels parameter will throw an error.

show_data_labels parameter could only be 1 or 0. If you want to display data labels on your chart, you should pass 1, otherwise you should pass 0.

show_data_labels parameter is optional. If you don't pass show_data_labels parameter, 1 will be passed by default.

Charts

Currently available chart types are bar, horizontal bar, line, area, pie, doughnut, funnel and pyramid charts. We want to add new chart types soon, if you want to create some other chart type via API, please contact us!

Request parameters are same on bar, horizontal bar, line and area charts to make chart creation easier.

Request parameters are also same on pie, doughnut, funnel and pyramid charts.

We will show you all request params for each chart. Let's begin with bar chart.

Bar Chart

A bar chart or bar graph is a chart or graph that presents categorical data with rectangular bars with heights or lengths proportional to the values that they represent.

Bar charts are very cool for comparison of small number of data points.

Bar Chart Request Params
{
    "theme": "zeus",
    "type": "bar",
    "title": "Test Chart For API",
    "label": "Test Label For API",
    "color": "#c23531",
    "chart_labels": ["1998","2000","2002","2004","2006","2008","2010","2012","2014","2016","2017"],
    "chart_data": ["3","7","10","14","18","23","29","34","40","46","48"],
    "show_data_labels": 1
}
Bar Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/HtfpJg.png"
}
Chart Image for example request
Horizontal Bar Chart

A horizontal bar chart is a version of bar chart, represent the data horizontally. It is a graph whose bars are drawn horizontally. The data categories are shown on the vertical axis and the data values are shown on the horizontal axis. The length of each bar is equal to the value corresponding the data category and all bars go across from left to right.

Horizontal Bar Chart Request Params
{
    "theme": "hera",
    "type": "horizontalBar",
    "title": "Horizontal Bar Chart For API",
    "label": "Horizontal Bar Label For API",
    "color": "#5470c6",
    "chart_labels": ["1998","2000","2002","2004","2006","2008","2010","2012","2014","2016","2017"],
    "chart_data": ["3","7","10","14","18","23","29","34","40","46","48"],
    "show_data_labels": 1
}
Horizontal Bar Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/FMjDKi.png"
}
Chart Image for example request
Line Chart

A line chart or line plot or line graph or curve chart is a type of chart which displays information as a series of data points called 'markers' connected by straight line segments. It is a basic type of chart common in many fields.

Line Chart Request Params
{
    "theme": "poseidon",
    "type": "line",
    "title": "Line Chart For API",
    "label": "Line Chart Label For API",
    "color": "#5470c6",
    "chart_labels": ["1998","2000","2002","2004","2006","2008","2010","2012","2014","2016","2017"],
    "chart_data": ["3","7","10","14","18","23","29","34","40","46","48"],
    "show_data_labels": 1
}
Line Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/ZZpWZB.png"
}
Chart Image for example request
Area Chart

An area chart is a line chart where the area between the line and the axis are shaded with a color.

Area Chart Request Params
{
    "theme": "apollo",
    "type": "area",
    "title": "Area Chart For API",
    "label": "Area Chart Label For API",
    "color": "#5470c6",
    "chart_labels": ["1998","2000","2002","2004","2006","2008","2010","2012","2014","2016","2017"],
    "chart_data": ["3","7","10","14","18","23","29","34","40","46","48"],
    "show_data_labels": 1
}
Area Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/Cy90zw.png"
}
Chart Image for example request
Pie Chart

A pie chart (or a circle chart) is a circular statistical graphic, which is divided into slices to illustrate numerical proportion. In a pie chart, the arc length of each slice (and consequently its central angle and area), is proportional to the quantity it represents.

Pie Chart Request Params
{
    "theme": "hermes",
    "type": "pie",
    "title": "Pie Chart For API",
    "label": "Pie Chart Label For API",
    "chart_labels": ["Oil","Coal","Gas","Nuclear","Hydro","Solar/Wind/Other"],
    "chart_data": [{"name":"Oil","value":"33"},{"name":"Coal","value":"27"},{"name":"Gas","value":"21"},{"name":"Nuclear","value":"6"},{"name":"Hydro","value":"2"},{"name":"Solar/Wind/Other","value":"11"}],
    "show_data_labels": 1
}
Pie Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/2pyVl4.png"
}
Chart Image for example request
Doughnut Chart

A doughnut (or donut) chart is a pie chart with a "hole" - a blank circular area in the center. The chart is divided into parts that show the percentage each value contributes to a total. Like the regular pie chart, the doughnut chart is used with small sets of data to compare categories. It drives attention from the area taken by each part to emphasize the length of arcs.

Doughnut Chart Request Params
{
    "theme": "aphrodite",
    "type": "doughnut",
    "title": "Doughnut Chart For API",
    "label": "Doughnut Chart Label For API",
    "chart_labels": ["Chrome","Firefox","IE","Safari","Edge","Opera"],
    "chart_data": [{"name":"Chrome","value":"54.66"},{"name":"Firefox","value":"13.96"},{"name":"IE","value":"11.97"},{"name":"Safari","value":"8.13"},{"name":"Edge","value":"8.24"},{"name":"Opera","value":"2.48"}],
    "show_data_labels": 1
}
Doughnut Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/dGLHd2.png"
}
Chart Image for example request
Funnel Chart

Funnel charts are a type of chart, often used to represent stages in a sales process and show the amount of potential revenue for each stage. This type of chart can also be useful in identifying potential problem areas in an organization’s sales processes.

A funnel chart displays values as progressively decreasing proportions amounting to 100 percent in total. The size of the area is determined by the series value as a percentage of the total of all values.

Funnel Chart Request Params
{
    "theme": "nemesis",
    "type": "funnel",
    "title": "Funnel Chart For API",
    "label": "Funnel Chart Label For API",
    "chart_labels": ["All Responses","Qualified","Sales Accepted","Sales Qualified","Closed Deals"],
    "chart_data": [{"name":"All Responses","value":"500"},{"name":"Qualified","value":"400"},{"name":"Sales Accepted","value":"300"},{"name":"Sales Qualified","value":"200"},{"name":"Closed Deals","value":"100"}],
    "show_data_labels": 1
}
Funnel Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/sS78qb.png"
}
Chart Image for example request
Pyramid Chart

A pyramid chart (also called a triangle diagram or a triangle chart) appears in the shape of a triangle divided into horizontal sections and is used to represent hierarchies. Because of the chart's shape, each section has a different size, and the width of each section indicates the level of hierarchy among each topic.

Pyramid Chart Request Params
{
    "theme": "artemis",
    "type": "pyramid",
    "title": "Pyramid Chart For API",
    "label": "Pyramid Chart Label For API",
    "chart_labels": ["Website Visits","Downloads","Interested to Buy","Purchased","Return"],
    "chart_data": [{"name":"Website Visits","value":"50"},{"name":"Downloads","value":"40"},{"name":"Interested to Buy","value":"30"},{"name":"Purchased","value":"20"},{"name":"Return","value":"10"}],
    "show_data_labels": 1
}
Pyramid Chart Successful Response Example
{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "https://chartsfactory.com/chartImages/WuNbLV.png"
}
Chart Image for example request

Chart Themes

There are 14 different chart themes, named after greek mythological figures.

All themes have different color schemes. It changes charts colors as well as background color.

You can try each theme and choose the best fit for your chart.

We will add more themes soon!

Errors

Charts Factory API uses HTTP response codes so you can understand which API request is successful or failed.

First, successful request:

API sends 200 response code. Also successful response example is:

{
    "status": "SUCCESS",
    "message": "Chart is generated successfully!",
    "url": "http://chartimages.chartsfactory.com/WuNbLV.png"
}

If there is a wrong or missing data type in your request, API also sends 200 response code. But failed response is a bit different:

{
    "status": "ERROR",
    "message": "Theme value type should be string!"
}

If you're getting 429 response code, it means that you are sending too many requests to API and you exceeded allowed rate limit.

You can send 100 requests in 1 minute.

If you're getting 500 response code, it means that there is something wrong with Charts Factory servers. You should contact us to solve the problem.

Limits and Quotas

You can send 100 requests in 1 minute per IP address.

If you exceed the quota, Charts Factory API returns 429 error code and you will be blocked for 1 minute.