API Documentation
The Infogr.am API platform connects your website or application with the infographics.

Infographic Content JSON Format

Overview

This page describes JSON format (or schema) which all infographic creation or alteration (update) request “content” field values have to comply with. Below is a sample of such infographic content:

[
    {
        "type": "h1",
        "text": "Testing API client"
    },
    {
        "type": "body",
        "text": "Lorem ipsum dolor sit amet..."
    },
    {
        "type": "quote",
        "text": "God does not play dice",
        "author": "Albert Einstein"
    },
    {
        "type": "chart",
        "chart_type": "pie",
        "data": [
            [
                ["apples", "today", "yesterday", "d. bef. yesterday"],
                ["John", 4, 6, 7],
                ["Peter", 1, 3, 9],
                ["George", 4, 4, 3]
            ]
        ],
        "settings": {
            "width": 0.5,
            "height": 300,
            "legend": true,
            "callouts": {
                "enabled": true,
                "percentage": true,
                "name": true
            }
        }
    },
    {
        "type": "map",
        "territory": "world",
        "data": [
            {
                "title": "Japan",
                "value": 126434964,
                "label": "Japan",
                "group": "A",
                "color": "#0000FF"
            },
            {
                "title": "United States",
                "value": 318968000,
                "label": "USA",
                "group": "A",
                "color": "#FF0000"
            }
        ]
    },
    {
        "type": "chart",
        "chart_type": "pictochart",
        "data": [
            [
                ["Population","1950","1960","1970","1980"],
                ["USA","151,869","179,980","203,985","227,225"],
                ["Japan","83,806","94,092","104,345","116,808"],
                ["Germany","68,375","72,481","72,481","78,298"],
                ["Brazil","53,444","71,412","94,931","12,1064"],
                ["United Kingdom","50,128","52,373","55,633","56,315"]
             ]
         ]
    }
]

Infographic Element Format

Infographic content is a JSON array each element of which describes individual element of that infographic, i.e., the infographic content is a JSON array of JSON hash objects.

Common Element Fields

Each infographic element must contain a field type which identifies the element type to be displayed, e.g., h1 or chart (see below). Optionally, infographic elements may contain settings field which is a JSON object. Allowed fields of this settings object depend on particular infographic element type.

Infographic settings Field

Name Type Description
width Number Width (a fraction) of an individual infographic element. Currently the only supported value is `0.5` which means that particular element width is half of the whole available width. This is meant for infographic element side by side placement.
height Number Height of a chart element
category_height Number Height of each bar representing a category in a bar chart. This option is mutually exclusive with `height`, i.e., they cannot be used together at once for a single chart element
decimal_separator String Which separator to use when converting passed number values as strings.
Possible values:
. - last occurance of point
, - last occurance of comma
., - last occurance of point or comma (try to avoid using this it is very confusing)
Please be aware passing values as numbers like ["John", 24.4, 61.7, 75.5] will ignore `decimal_separator` till you edit data in infogram application. Please use ["John", "24.4", "61.7", "75.5"] instead.
legend Boolean Controls whether to display chart legend or not (where applicable - depending on the chart type). Default: true
callouts Object callouts structure is a JSON object that controls display of callouts for charts where it is applicable. The object consists of multiple fields:
  • enabled - Booleam value controlling callouts on/off. Default false
  • percentage - Boolean value controlling callout values are shown in absolute values (default) or percent (value true). Default false
  • name - Boolean - display legend names in callout. Default false

Infographic Element Types

  • h1 - represents the headline of an infographic. Text with large font size with (usually) uppercased letters.
    Name Type Required Description
    type String true Should be equal to h1
    text String true Text contents of the headline
  • h2 - represents the chart title in an infographic. Text with usually a bit smaller font size than h1.
    Name Type Required Description
    type String true Should be equal to h2
    text String true Text contents of the chart title
  • body - represents the body text in an infographic. Can be used to display larger text block with regular font size.
    Name Type Required Description
    type String true Should be equal to body
    text String true Text contents of the "body text"
  • quote - represents a quote in an infographic. Consists of the quote text and text containing a reference to the author.
    Name Type Required Description
    type String true Should be equal to quote
    text String true Text contents of the quote
    title String true Text containing reference to the quote author
  • separator - represents the line in an infographic.
    Name Type Required Description
    type String true Should be equal to separator
  • chart - represents a chart in an infographic
    Name Type Required Description
    type String true Should be equal to chart
    chart_type String true Chart type identifier. Choose on from the list of Chart Types
    data Array true A 3-dimensional array consisting of chart data, see the Chart Data Format section
    colors Array false An array containing explicitly set colors for rows. Each color item represents particular row in order they follow in data array. Colors are represented as standard HTML/CSS hex colors, e.g. #FF00BB
    icon String false For table charts only, icon identifier from a predefined set of all available icons. If present, the designated icon will be displayed in table cells instead of the actual data (where present). To change icon color, use the colors field
  • map - represents a map in an infographic
    Name Type Required Description
    type String true Should be equal to map
    territory String true Territory identifier this map to display. It should be equal to one of the available map identifiers, see section Available Maps
    data Array true Array consisting of data to display the map, see the Map Data Format section
  • facts_and_figures - represents "Facts and Figures" object in an infographic
    Name Type Required Description
    type String true Should be equal to facts_and_figures
    data Array true Array consisting of data to display Facts and Figures, see the Facts and Figures Data Format section

    Example:

         [
             {
                 "type": "facts_and_figures",
                 "data": [
                     {
                         "icon": "profile",
                         "figure": "100,000",
                         "fact": "Number of times average human heart beats per day.",
                         "color": "#AA0000"
                     },
                     {
                         "icon": "up",
                         "figure": "50,000",
                         "fact": "Number of English words the average lead pencil writes during its life span.",
                         "color": "#0000AA"
                     }
                 ]
             }
         ]
    

Chart Types

Type Description
bar Bar
bar-stacked Stacked bar
bar-grouped Grouped bar
bar-radial Radial bar
column Column
column-stacked Stacked column
column-grouped Grouped column
column-radial Radial column
pie Pie
pie-doughnut Doughnut
pie-irregular Irregural pie
pie-semi-circle Semi Circle
line Line
area Area
area-stream Steam graph
area-stepped Stepped area
scatter Scatter
scatter-dotplot Dot plot
bubble Bubble
bubble-plot Bubble plot
pictochart Pictorial
pictochart-sizes Size comparison
pictochart-pictorial Pictorial bar
hierarchy-pyramid Pyramid
hierarchy-funnel Funnel
table Table
progress-gauge Progress gauge
progress-bar Progress bar
wordcloud World cloud
treemap Treemap
candlestick Candle stick
waterfall Waterfall

Chart Data Format

Chart data is represented by a JSON object which has field sheets on its top level. That field value is a JSON array which represents data sheets (think of Microsoft Excel).

Each sheet consists of two arrays: header and rows:

  • header is an array that contains sheet table’s header names, i.e., it is an array of strings
  • rows is an array that represents sheet table’s data rows, it is an array with objects containing the following fields:

    Name Type Required Description
    header String false Row title
    data Array true Row data
    color Array false color representing particular row in HTML/CSS hex format, e.g., `#FFDD00`. Optional. If present, it overrides the row's color value that is set in a `colors` array of the chart

Map Data Format

Chart data is represented by a JSON array where each item represents certain subdivision of territory displayed by the map. Each element of that array has or may have the following fields:

Name Type Required Description
title String true Title of a map item. Usually an English name of the territory subdivision, must be a valid territory region name. List of valid regions of a particular map can be found in the Available Maps table
value Number true Value representing map item
label String false Overrides title of the map item. This provides ability to change the visible title of a particular map region.
group String false Arbitrary string identifying a group this item is in. This allows to visually group certain map regions by color.
color String false Allows to specify arbitary color for specific map region. Use color HTML hex notation, like #FFDD88

Available Maps

Identifier Description File to subdivision data

Facts and Figures Data Format

Facts and Figures data is represented by an array where each element is in the following format:

Name Type Required Description
icon String false Icon identifier from a predefined set of all available icons
figure String | Integer | Boolean false Value, figure itself
fact String false A fact, description backing up the figure
color String false Color of the row in "Facts and Figures" object

Available Facts and Figures Icons

Identifier Availability Icon sample

Examples

A wordcloud displaying most frequent last names of people in Japan, England, and USA:

{
    "type": "chart",
    "chart_type": "wordcloud",
    "data": {
        "sheets": [
            {
                "header": [ "Japan", "%"  ],
                "rows": [
                    {
                        "color": "FC14F9",
                        "data": [ "Sato",  1.57 ]
                    },
                    [ "Suzuki", 1.50 ],
                    [ "Takahashi", 1.16 ]
                ]
            },
            {
                "header": [ "England", "%" ],
                "rows" : [
                    [ "Smith", 1.26 ],
                    [ "Jones", 0.75 ],
                    [ "Taylor", 0.59 ]
                ]
            },
            {
                "header": [ "USA", "%" ],
                "rows" : [
                    [ "Smith", 0.88  ],
                    [ "Johnson", 0.69 ],
                    [ "Williams", 0.57 ]
                ]
             }
         ]
     },
    "colors" : ["#1D7BF5", "#599AF0", "#95BFF5", "#1DF548", "#5EF27C", "#83D693", "#CC2929", "#BF5A5A", "#EDC7C7"]
}

A chart showing affiliation of some countries to certain organizations:

{
    "type": "chart",
    "chart_type": "table",
    "data": {
        "sheets": [
            {
                "header": [ "Membership", "United Nations", "NATO", "G7", "EU" ],
                "rows": [
                    {
                        "header": "China",
                        "data": [ "x", "", "", "" ]
                    },
                    {
                        "header": "France",
                        "data": [ "x", "x", "x", "x" ]
                    },
                    {
                        "header": "Germany",
                        "data": [ "x", "x", "x", "x" ]
                    },
                    {
                        "header": "USA",
                        "data": [ "x", "x", "x", "" ]
                    }
                ]
            }
        ]
    }
}

A map displaying a few contries and their population:

[
    {
        "type": "map",
        "territory": "world",
        "data": [
            {
                "title": "Japan",
                "value": 126434964,
                "label": "Japan",
                "group": "A",
                "color": "#0000FF"
            },
            {
                "title": "United States",
                "value": 318968000,
                "label": "USA",
                "group": "A",
                "color": "#FF0000"
            },
            {
                "title": "China",
                "value": 1357380000,
                "label": "China DPR",
                "group": "B"
            },
            {
                "title": "India",
                "value": 1210193422,
                "label": "India",
                "group": "C",
                "color": "#FFFF00"
            }
        ]
    }
]