Publishing a Visualization

Here you will learn how to use Datawrapper's API to publish your charts.

Before you get going with publishing, it might be good to know how to check the publish status of a chart. Has it already been published? If yes, when and how many times?

To do so, perform a GET request on your chart. Make sure to replace the <ID> with your chart ID (a 5 chracter ID like "384dj") and the <YOUR_TOKEN_HERE> with your API Access Token:

curl --request GET \
  --url https://api.datawrapper.de/v3/charts/<ID> \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \

Below is an abridged response to a GET request made on a chart that has not yet been published:

{
  "id": "aBcDe",
  "lastEditStep": 2,
  "publishedAt": null,
  "publicUrl": null,
  "publicVersion": 0,
  "metadata": {
    "publish": {
      "embed-width": 536,
      "embed-height": 674
    },
    ...
  },
  "url": "/v3/charts/aBcDe",
  ...
}

It is easy to recognize that this chart is still unpublished thanks to the values of four properties. The table below explains them in detail:

Name

Value when unpublished

lastEditStep

1 - 4

publishedAt

null

publicUrl

null

publicVersion

0

Publish a visualization

To publish (and republish) a chart, make the following POST request:

curl --request POST \
  --url https://api.datawrapper.de/v3/charts/<ID>/publish \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

This can take a few seconds. You can check the progress with the following GET request. It returns a list of steps that have completed for the chart to get published:

curl --request GET \
  --url https://api.datawrapper.de/v3/charts/<ID>/publish/status/<VERSION> \
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Your POST request will return the data for your chart, including its newly generated embed codes and public URL. You can check if your chart is published with the URL https://www.datawrapper.de/_/<ID>, like so: https://www.datawrapper.de/_/HpeMi

{
    "version": 1,
    "url": "//datawrapper.dwcdn.net/aBcDe/1/",
    "data": {
        "metadata": {
            "publish": {
                "embed-width": 500,
                "embed-height": 600,
                "embed-codes": {
                    "embed-method-iframe": "<iframe src= ..... ></iframe>",
                    "embed-method-responsive": "<iframe id= .... ></iframe <script type= ....></script>"
                }
            },
              ...
        },      
        "lastEditStep": 5,
        "publishedAt": "2018-01-21 09:14:12",
        ...
            }
        }
    }
}

Let's look at the returning properties in detail.
Here you can find a the reference on all publish-related chart attributes. If you still have questions, our Academy article "How to embed charts" might help.

Name

Type

Description

embed‑width

Number

The width of the embedded chart. This will already be defined and present in the chart data even before publishing.

embed‑height

Number

The heigh of the embedded chart. This will already be defined and present in the chart data even before publishing.

embed‑codes

String

This section is only present if the chart is published. It contains the two embed codes described below.

embed‑method‑iframe

String

This is the embed code for a non-responsive iframe. It consists of just an iframe. Do not change any parts of this embed code.

embed‑method‑responsive

String

This is the embed code for a responsive iframe, it consists of an iframe and a script. Do not change any parts of this embed code.

lastEditStep

Number

This defines what stage your chart is in. Stages 1-4 are pre-publishing.

1: Upload
2: Describe
3: Visualize
4: Publish page accessed

5: Chart Published

publishedAt

Date
YYYY‑MM‑DD

This is date and time that the chart was last published.

And that's it! You successfully published a visualization.

Copy the (responsive) embed code in your article or share the URL to your visualization on social media.