External data sources and live-updating visualizations

You can link a Datawrapper visualization to a Google Sheet, or create a live-updating visualization by connecting it to an external data source. This article explains how to do so with the API.

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.

  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.

To link a visualization to a Google Sheet, 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 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}


    You’ll find both IDs in the URL of your Google Sheet when you open it in your browser. The DOCUMENT_ID is the long string of letters, numbers, dashes, and underscores between /d/ and /edit. The SHEET_ID is the number that comes after gid= at the end of the URL. Each tab in your spreadsheet has its own sheet ID, so make sure you’ve opened the tab that contains your data before you copy it.

Depending on whether you want to serve the data directly or have us serve the data for you, the configuration is 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.

For visualizations with live-updating metadata (like a chart description that updates), you can also include a JSON source URL under external-metadata in the data section of your metadata configuration. Here's more information and an explanation on how to do so in the app.