Visualization Properties

How to GET visualization properties

This request returns the details and precise configuration of a specific chart, map, or table. Below are a sample request and the result:

curl  --request GET \
    --url https://api.datawrapper.de/v3/charts/6Ba3L \
    --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'
{
  "id": "6Ba3L",
  "type": "d3-scatter-plot",
  "title": "A great chart",
  ...
  
  "metadata": {
    
    "data": {
      "transpose": false,
      ...
    },
      
    "publish": {
      "embed-codes": {
        "embed-method-iframe": "<iframe title=\"\" aria-label=\"Scatter Plot\" src=\"//datawrapper.dwcdn.net/6Ba3L/1/\" scrolling=\"no\" frameborder=\"0\" style=\"border: none;\" width=\"600\" height=\"294\"></iframe>",
        ...
      },
      "embed-width": 600,
      "chart-height": 33.859375,
        ...
      }
    },
      
    "annotate": {
      "notes": "Updates from 2018 are excluded."
    },
      
    "describe": {
      "intro": "",
      "byline": "",
      ...
    },
      
    "visualize": {
      "size": "fixed",
      "rules": false,
      "shape": "fixed",
      ...
    },
      
    "json_error": null
  },
    
  "language": "en-US",
  "externalData": null,
  ...
  },
  "url": "/v3/charts/6Ba3L"
}%

Regardless of chart, map or table type, the structure will always be the same:

The top-level properties describe describe attributes like the id, type, title of the chart. Probably the most important top-level property is the metadata, which contains all of the settings for the visualization, you can find out more about how the metadata is structured below.

1. Top level properties

Let's start with an overview of all the top-level properties excluding the metadata. These are identical for every chart, map or table.

{
  "id": "6Ba3L",
  "type": "d3-scatter-plot",
  "title": "",
  "theme": "default",
  "lastEditStep": 3,
  "publishedAt": null,
  "publicUrl": null,
  "publicVersion": 0,
  "deleted": false,
  "deletedAt": null,
  "forkable": false,
  "isFork": false,
  "metadata": {
    ...
  },
  "language": "en-US",
  "externalData": null,
  "utf8": false,
  "createdAt": "2019-11-06T13:34:28.000Z",
  "lastModifiedAt": "2019-11-07T09:34:16.000Z",
  "forkedFrom": null,
  "folderId": null,
  "organizationId": null,
  "authorId": 62982,
  "author": {
    "name": "Lisa Charlotte Rost",
    "email": "[email protected]"
}

Name

Type

Description

id

String

The unique 5-character case-sensitive chart ID that gets assigned to every Datawrapper chart, e.g. 3TS8S (You can check the ID of published charts with placing it in https://www.datawrapper.de/_/3TS8S/.)

type

String

What type of chart, map or table this is (e.g line chart, locator map, scatterplot etc). Visit the page "Chart Types" to learn how each visualization type is called.

title

String

The title of your chart, e.g. "Life Happiness Index, globally".

theme

String

The design theme that the chart uses. "Default" means that it uses the theme that you set as default in your team settings. If you don't have a Custom plan, the theme will be the default Datawrapper theme and you won't be able to change it.

lastEditStep

Number

Furthest step reached in chart creation.
1 = Upload | 2 = Describe | 3 = Visualize | 4 = Visited publish page, but not yet published | 5 = Chart published

publishedAt

String

Date and time published, in the format YYYY-MM-DD0 HH:MM:SS. This property is null when the chart is not published yet.

publicUrl

String

URL where the chart can be found, e.g.
//datawrapper.dwcdn.net/6Ba3L/1/ This property is null when the chart is not published yet.

publicVersion

Number

How many times the chart has been published. This property is null when the chart is not published yet.

deleted

Boolean

True if deleted. False if not deleted.

deletedAt

String

Date and time deleted in the format YYYY-MM-DD0 HH:MM:SS. This property is null when the chart is not deleted.

forkable

Boolean

true if chart is in the Datawrapper River.

isFork

Boolean

true if chart is duplicated from a Datawrapper River chart

metadata

Object

Contains all further chart settings. These are outlined in more detail below.

language

String

The chart locale, e.g. en-US or de-DE.

externalData

String

URL to live CSV data. This property is null when the chart doesn't link to live data.

utf8

Boolean

true if the chart uses the character encoding UTF-8.

createdAt

String

Date and time when the chart was created in the format YYYY-MM-DD0 HH:MM:SS.

lastModifiedAt

String

Date and time when the chart was last changed (by anyone) in the format YYYY-MM-DD0 HH:MM:SS.

forkedFrom

Boolean

Chart ID of the original chart that was then re-used (="forked") from the River. This property is null when the chart was not forked from the River.

folderId

String

ID of the folder the chart is in. This property is null when the chart has not been moved to a folder yet.

organizationId

String

ID of the team the chart is in. This property is null when the chart is not moved to a team yet, but part of "MyCharts".

authorID

Number

User ID of the person who created the chart, e.g. 62982

guestSession

Boolean

True if chart was created by a user who doesn't have a Datawrapper account. Otherwise false.

The Metadata

All of your chart settings, for example everything you enter in the Annotate section (Byline, Notes, Description), or everything you configure in the Refine tab (number format, custom range, line-widths etc.) are stored in the top-level metadata property. The metadata object itself will always contain the following:

  1. Data - describes how you configured your data
  2. Describe -contains properties like the byline, source URL and description
  3. Annotate - contains the chart notes
  4. Axes - describes which columns of your dataset are being used for what
  5. Visualize - contains configurations for all the visual elements of the chart, like markers, shapes, line widths or colors.
  6. Publish - contains details like the embed code and width/height configurations

Lets go through these in some more detail:

1. Data properties

The data properties change depending on the visualization type (locator map, choropleth map, table, line chart, etc.) and the changes in step 2: Check & Describe. For example, when the column order isn't changed, the query won't include the part column-order in the data property.

Here are some possible returned properties:

{
  ...
    "data": {
      "transpose": false,
      "vertical-header": true,
      "horizontal-header": true
      "json": true,
      "changes": [
        {
          "row": 9,
          "time": 1573134075869,
          "value": "1.7",
          "column": 3,
          "previous": "0.7"
        },
        {
          "row": 0,
          "time": 1573134111144,
          "value": "Extra column",
          "column": 5
        }
      ],
      "column-order": [
        2,
        0,
        1
      ],
      "column-format": {
        "Column A": {
          "type": "text",
          "ignore": false,
          "number-append": "",
          "number-format": "n1",
          "number-divisor": 0,
          "number-prepend": ""
        }
      }
    },
    ...
}

Name

Type

Description

transpose

Boolean

True if the data is transposed (=rows and columns switched).

changes

Object

Changes made to a data set in step 2: Check & Describe, e.g. columns added or cell values overwritten.

changes.row

Number

The row (index) with the change (0 = first row). If a column is added, the row is 0.

changes.time

Number

Unix time in milliseconds when the change was made, e.g. 1573134075869.

changes.value

String

The value that overwrites the original value. If a column is added, this property returns the name of the new column.

changes.column

Number

The column (index) with the change (0 = first column).

changes.previous

String

The original value that is overwritten. This property doesn't exist in added columns.

column-order

Array

Order of the columns (0 = first column).

column-format

Object

Possible properties when the column format (text, data, number, auto) changes or a prefix/suffix is added, or the number is rounded or divided.

2. Describe properties

The Describe properties include all information (except the notes and the title) that you'll input under Annotate your chart/map in the Annotate tab in step 3: Visualize. It also contains some extra information about added columns from step 2: Check & Describe.

{
  ...
  "describe": {
      "intro": "US Population, 1950-2019.",
      "byline": "Lisa Charlotte Rost, Datawrapper",
      "source-url": "http://data.un.org/",
      "source-name": "UN Data",
      "number-append": "",
      "number-format": "-",
      "number-divisor": 0,
      "number-prepend": "",
      "computed-columns": {
        "Column 1": "Extra column"
      }
    },
    ...
}

3. Annotate properties

The Annotate properties don't contain any information about the text annotations you'll find in line charts, area charts or scatterplots. It just contains the Notes from the Annotate tab in step 3: Visualize:

{
  ...
  "annotate": {
      "notes": "Updates from 2018 are excluded."
    },
  ...
}

4. Axes

The 'axes' of your chart specify what columns are being used for what. For example, which column is used for the colors, labels, grouping etc. The available axes will depend on the visualization type. The following is an example for a scatter plot, which has 5 'axes'.

{
  "x":"GDP per capita",
  "y":"Life expectancy",
  "size":"Population",
  "color":"Continent",
  "labels":"Country"
}

5. Visualize properties

Visualize properties will vary depending on your visualization type and changes to the chart. It contains the most properties of them all.

📘

Play around to find out more

We won't have the capacity to explain every single Visualize property from every single of our more than 20 visualization types. But here are some good news: Most of them are self-explanatory! To learn what specific properties are doing, consider creating a chart with which you can play around, change settings – and then see what changes when you run a query on this chart. Repeat as much as you want.

6. Publish properties

In the Publish object you'll find details like the embed codes and chart dimensions.

{
  ...
  "publish": {
        "text": "#333333",
        "background": "#ffffff",
        "embed-codes": {
          "embed-method-iframe": "<iframe title=\"\" aria-label=\"Scatter Plot\" src=\"//datawrapper.dwcdn.net/6Ba3L/1/\" scrolling=\"no\" frameborder=\"0\" style=\"border: none;\" width=\"600\" height=\"294\"></iframe>",
          "embed-method-responsive": "<iframe title=\"\" aria-label=\"Scatter Plot\" id=\"datawrapper-chart-6Ba3L\" src=\"//datawrapper.dwcdn.net/6Ba3L/1/\" scrolling=\"no\" frameborder=\"0\" style=\"width: 0; min-width: 100% !important; border: none;\" height=\"294\"></iframe><script type=\"text/javascript\">!function(){\"use strict\";window.addEventListener(\"message\",function(a){if(void 0!==a.data[\"datawrapper-height\"])for(var e in a.data[\"datawrapper-height\"]){var t=document.getElementById(\"datawrapper-chart-\"+e)||document.querySelector(\"iframe[src*='\"+e+\"']\");t&&(t.style.height=a.data[\"datawrapper-height\"][e]+\"px\")}})}();\n</script>"
        },
        "embed-width": 600,
        "chart-height": 205,
        "embed-height": 294
      },
    ...
}

Name

Type

Description

text

String

background

String

The background color of the visualization.

embed-codes.embed-method-iframe and embed-codes.embed-method-responsive

String

Full embed codes for the visualization. To learn more about the difference between the two embed codes, visit this Academy article.

embed-width

Number

Default Iframe width.

chart-height

Number

Default visualization height without header and footer.

embed-height

Number

Default Iframe height.