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. |
Updated over 1 year ago