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": "datawrapper",
  "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 ID of the design theme that the chart uses. You can find out which themes are available to you using the GET /themes endpoint.
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:

Data - describes how you configured your data
Describe -contains properties like the byline, source URL and description
Annotate - contains the chart notes
Axes - describes which columns of your dataset are being used for what
Visualize - contains configurations for all the visual elements of the chart, like markers, shapes, line widths or colors.
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",
      "aria-description": "Alternative description text",
      "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.

How to GET visualization properties

1. Top level properties

The Metadata

1. Data properties

2. Describe properties

3. Annotate properties

4. Axes

5. Visualize properties

📘Play around to find out more

6. Publish properties

📘
Play around to find out more