Connecting visualizations to external data sources

You might already be familiar with Datawrapper's features for linking a visualization to a Google Sheet, or creating a live-updating visualization by connecting it to an external data source.

This guide will outline how to create charts like this using the API alone.

Configuring external data sources comes down to setting the appropriate chart metadata for your needs. If you're not yet familiar with the concept of the chart metadata, or how to create or update a chart using the API, please start by referring to our guide on creating a chart.

What options are there for linking external data?

  1. Connect Google Sheet
    In this case, the chart will pull data from a Google Sheet. You'll see the latest data from the sheet appear in the visualization whenever you edit or publish it. However, this type of visualization will not update automatically after it has been published. If you want your published chart to reflect the latest state of the data in the sheet, you'll need to republish it.

  1. Link External Data (aka live-updating visualizations)
    This allows you to configure your visualization to pull data from any CSV source. In addition, the published chart will automatically update from the source data - without any need for you to republish the chart. Note that it's also possible to use a Google Sheet as a live-updating external data source.

Read on for the specifics on how to configure charts like this using the API.

Connect Google Sheet

In order to link a visualization to a Google Sheet, you will need to set the following in the metadata of your visualization:

{
    "metadata": {
        "data": {
            "upload-method": "google-spreadsheet",
            "google-spreadsheet": "https://docs.google.com/spreadsheets/d/{DOCUMENT_ID}/edit#gid={SHEET_ID}",
            "google-spreadsheet-src": "https://docs.google.com/spreadsheets/d/{DOCUMENT_ID}/export?format=csv&id={DOCUMENT_ID}&gid={SHEET_ID}"
        }
    }
}

There are three components to this:

  1. metadata.data.upload-method

    For a simple (not live-updating) visualization linked to a Google Sheet, set the upload method to be google-spreadsheet

  2. metadata.data.google-spreadsheet

    This is the share URL of your Google Sheet, which you would usually paste into Datawrapper.

    It's the URL in the address bar when you've got the sheet open (also the URL that Google generates when you enable sharing).

  3. metadata.data.google-spreadsheet-src

    In order for the Datawrapper chart to be able to read the data from the Google Sheet, google-spreadsheet-src is also required. This is the CSV export URL of the Google Sheet. It can be constructed from the google-spreadsheet URL, following this template: https://docs.google.com/spreadsheets/d/{DOCUMENT_ID}/export?format=csv&id={DOCUMENT_ID}&gid={SHEET_ID}

    Where the DOCUMENT_ID and SHEET_ID can be found in the google-spreadsheet URL:

In this case, depending on whether you want to serve the data directly, or have us serve the data for you, the configuration will be slightly different. Examples of the required settings in both scenarios can be seen in the snippets below, followed by an explanation of each of them.

{
  "metadata": {
    "data": {
      "upload-method": "external-data",
      "external-data": "https://data.some-domain.com/hourly-dataset.csv",
      "use-datawrapper-cdn": true
    }
  },
  "externalData": "https://static.dwcdn.net/data/{CHART_ID}.csv"
}
{
  "metadata": {
    "data": {
      "upload-method": "external-data",
      "external-data": "https://data.some-domain.com/hourly-dataset.csv",
      "use-datawrapper-cdn": false
    }
  },
  "externalData": "https://data.some-domain.com/hourly-dataset.csv"
}

The four configuration parameters for live-updating external data are:

  1. metadata.data.upload-method — Set to external-data.
  2. metadata.data.external-data — The URL to your CSV data source.
  3. metadata.data.use-datawrapper-cdn — true to have Datawrapper serve the data, or false to serve it directly from your server.
  4. externalData — The URL from which the published chart loads data. When using the Datawrapper CDN, this follows the pattern: https://static.dwcdn.net/data/{CHART_ID}.csv.

Using external metadata

For visualizations with live-updating metadata, you can also include a JSON source URL under external-metadata in the data section of your metadata configuration.