Moving a visualization

Folders help organize your visualizations and the visualizations of your team. In this article, you will learn how to move a visualization from one folder to another with the API. (Learn here how to do so in the app.)

All folders have an ID. Each visualization stores the ID of its folder in a property called folderId.

To find the folder ID, you can request a list of all folders associated with your account.

curl --request GET \
     --url https://api.datawrapper.de/v3/folders \
     --header 'authorization: Bearer <YOUR_AUTH_TOKEN>'

A successful response looks like this:

{
  "list": [
    {
      "type": "user",
      "id": 179729,
      "charts": [
        {
          "id": "n3ndy",
          "title": "Marvel Cinematic Universe locations in Europe",
          ...
        }
      ],
      "folders": [
        {
          "id": 12642,
          "name": "Marvel Charts",
          "charts": [],
          "folders": []
        }
      ]
    }
  ],
  "total": 1
}

We see that our chart about Marvel is currently not in the "Marvel Charts" folder, where it belongs. The next thing we see in this response is that the folder ID I'm looking for is 12642 and the chart ID is n3ndy. We need both IDs to move the correct chart, so let's do that.

To move a visualization, use PATCH /v3/charts/:id and send the folder ID as the request body, like so:

curl  --request PATCH \
      --url https://api.datawrapper.de/v3/charts/n3ndy \
      --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
	    --header 'content-type: application/json' \
      --data \
     '{
        "folderId": 12642
      }'

Assuming everything went well, your response will show the visualization metadata with the newly changed folder ID:

{
  "id": "n3ndy",
  "folderId": 12642,
  ...
  "url": "/v3/charts/n3ndy"
}

This is it! We successfully moved a visualization into a different folder.

Now you know how to move an existing visualization around – but what about new ones? Luckily, it is possible to create visualizations immediately in the right folder. To do so, use POST /v3/charts/ to create a new chart (learn more in our Creating a chart guide) and add the right folder ID:

curl --request POST \
     --url https://api.datawrapper.de/v3/charts \
     --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
     --header 'content-type: application/json' \
     --data '{ 
       "title": "Draft: Secret Marvel Chart", 
       "type": "d3-bars-stacked",
       "folderId": 12642,
     }'