Datawrapper API

Here’s an example of using Datawrapper’s script embed API to embed a Datawrapper chart in Observable Framework. And below, we show how to use a data loader to generate a new Datawrapper chart on demand.

Script embed

The chart below is from a recent Datawrapper blog post on Spotify trends.

To embed a Datawrapper chart in Framework, copy and paste its script embed code. You can find this code by choosing Embed with script in Datawrapper’s embed modal; see Datawrapper’s embedding guide for details.

<div class="card" style="max-width: 908px;">
  <script data-dark="auto" defer src="https://datawrapper.dwcdn.net/OuHrk/embed.js"></script>
</div>

Setting the data-dark attribute to auto will respect the user’s preferred color scheme and assumes you are using a responsive theme in Framework. If you are forcing a dark theme, set this attribute to true instead; or for a light theme, set this attribute to false.

Using a data loader

You can dynamically generate Datawrapper charts with a Python data loader that uses the Datawrapper API. The loader will return the chart’s unique identifier, which you can then use to embed the chart in your page.

import sys

import pandas as pd
from datawrapper import Datawrapper

# Read in the data file, which is drawn from a Datawrapper example
# https://academy.datawrapper.de/article/281-examples-of-datawrapper-dot-charts
df = pd.read_csv("src/data/chart.csv")

# Connect to the Datawrapper api
dw = Datawrapper()

# Search if the chart already exists
title = "Germany is the third-oldest country in the world"
search_result = dw.get_charts(search=title)

# If the chart already exists, return its id
if search_result['list']:
    chart_id = search_result['list'][0]["id"]
    sys.stdout.write(chart_id)
    sys.exit()

# If it doesn't exist, create the chart
chart_config = dw.create_chart(
    # Headline the chart
    title=title,
    # Set the type
    chart_type="d3-dot-plot",
    # Give the data
    data=df,
    # Configure everything about the chart
    metadata={
        # Set the description
        "describe": {
            "intro": "Median age in the three countries with the oldest population and selected other countries, in years",
            "source-name": "Estimates by the CIA World Factbook, 2018",
            "source-url": "https://www.cia.gov/library/publications/resources/the-world-factbook/fields/343rank.html",
        },
        # Configure the chart
        "visualize": {
            "custom-range": [
                "35",
                "55"
            ],
            "range-extent": "custom",
            "highlight-range": True,
            "replace-flags": {
                "style": "4x3",
                "enabled": True
            },
            "color-by-column": True,
            "show-color-key": True,
            "color-category": {
                "map": {
                    "Male": "#94c4d1",
                    "Female": "#ffca76",
                    "Combined": "#545a5d"
                },
            },
        },
        "publish": {
            "autoDarkMode": True,
        },
    }
)

# Pull out the chart's unique identifier
chart_id = chart_config["id"]

# Publish the chart
dw.publish_chart(chart_id)

# Write the chart's unique identifier to stdout
sys.stdout.write(chart_id)

You’ll also need python3 and the pandas and datawrapper modules installed and available on your $PATH.

We recommend using a Python virtual environment, such as with venv or uv, and managing required packages via requirements.txt rather than installing them globally.

You will also need to create an API token with Datawrapper and set it as an environment variable named DATAWRAPPER_ACCESS_TOKEN. You can learn how by visiting the site's “Getting Started” guide. You'll want to give the token permission to create and publish charts (see the reference documentation for details).

The above data loader lives in data/chart.txt.py, and creates the data/chart.txt file attachment, which contains the identifier. Since the identifier is dynamically constructed by the data loader, we can’t hard-code the identifier in HTML; instead, we’ll use a JavaScript helper function to create the embed script.

function DatawrapperChart(chartId) {
  const script = document.createElement("script");
  script.setAttribute("data-dark", dark);
  script.setAttribute("src", `https://datawrapper.dwcdn.net/${chartId}/embed.js`);
  return script;
}

Lastly, we can read load the generated chart’s identifier and pass it to the helper to display the chart:

<div class="card" style="max-width: 908px;">
  ${DatawrapperChart(await FileAttachment("data/chart.txt").text())}
</div>