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]"
}
NameTypeDescription
idStringThe 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/.)
typeStringWhat 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.
titleStringThe title of your chart, e.g. "Life Happiness Index, globally".
themeStringThe ID of the design theme that the chart uses. You can find out which themes are available to you using the GET /themes endpoint.
lastEditStepNumberFurthest step reached in chart creation.
1 = Upload | 2 = Describe | 3 = Visualize | 4 = Visited publish page, but not yet published | 5 = Chart published
publishedAtStringDate and time published, in the format YYYY-MM-DD0 HH:MM:SS. This property is null when the chart is not published yet.
publicUrlStringURL where the chart can be found, e.g.
//datawrapper.dwcdn.net/6Ba3L/1/ This property is null when the chart is not published yet.
publicVersionNumberHow many times the chart has been published. This property is null when the chart is not published yet.
deletedBooleanTrue if deleted. False if not deleted.
deletedAtStringDate and time deleted in the format YYYY-MM-DD0 HH:MM:SS. This property is null when the chart is not deleted.
forkableBooleantrue if chart is in the Datawrapper River.
isForkBooleantrue if chart is duplicated from a Datawrapper River chart
metadataObjectContains all further chart settings. These are outlined in more detail below.
languageStringThe chart locale, e.g. en-US or de-DE.
externalDataStringURL to live CSV data. This property is null when the chart doesn't link to live data.
utf8Booleantrue if the chart uses the character encoding UTF-8.
createdAtStringDate and time when the chart was created in the format YYYY-MM-DD0 HH:MM:SS.
lastModifiedAtStringDate and time when the chart was last changed (by anyone) in the format YYYY-MM-DD0 HH:MM:SS.
forkedFromBooleanChart 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.
folderIdStringID of the folder the chart is in. This property is null when the chart has not been moved to a folder yet.
organizationIdStringID 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".
authorIDNumberUser ID of the person who created the chart, e.g. 62982
guestSessionBooleanTrue 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": ""
        }
      }
    },
    ...
}
NameTypeDescription
transposeBooleanTrue if the data is transposed (=rows and columns switched).
changesObjectChanges made to a data set in step 2: Check & Describe, e.g. columns added or cell values overwritten.
changes.rowNumberThe row (index) with the change (0 = first row). If a column is added, the row is 0.
changes.timeNumberUnix time in milliseconds when the change was made, e.g. 1573134075869.
changes.valueStringThe value that overwrites the original value. If a column is added, this property returns the name of the new column.
changes.columnNumberThe column (index) with the change (0 = first column).
changes.previousStringThe original value that is overwritten. This property doesn't exist in added columns.
column-orderArrayOrder of the columns (0 = first column).
column-formatObjectPossible 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
      },
    ...
}
NameTypeDescription
textString
backgroundStringThe background color of the visualization.
embed-codes.embed-method-iframe and embed-codes.embed-method-responsiveStringFull embed codes for the visualization. To learn more about the difference between the two embed codes, visit this Academy article.
embed-widthNumberDefault Iframe width.
chart-heightNumberDefault visualization height without header and footer.
embed-heightNumberDefault Iframe height.