Guides

Response Types

Almost every time you send a API request, you will get a response. This article explains the different kinds of responses you can expect from sending requests with the Datawrapper API.

JSON format

Most of your responses will be JSON formatted. JSON stands for JavaScript Object Notation and is a simple human-readable format to transfer data between applications. Here's an example of a JSON file:

{
  "name": "Gwen Stacy",
  "occupation": "Student",
  "height": 170,
  "relatives": [
    "Helen Stacy", 
    "George Stacy"
  ]
}

You can easily see that this is about a student called Gwen Stacy. Datawrapper API responses look very similar and you have already seen one in the Getting started section. If you want to learn more about JSON, follow this link: An introduction to JSON.

JSON format: Single resource endpoints

Our API can give you back two different kinds of responses: Responses about single resources and about multiple resources. Let's look at both of them to learn the difference.

A single resource query will return information about, well, a single resource – like one chart, or one user, or one team. Here are an example request and response. In this case, we want to get some information about the visualization with the id <ID>. 

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

This is what comes back: A big JSON that tells us that the visualization which ID we entered is a locator map with the title "New York City sights" that I published in November 2019:

{
  "id": "1vXs6",
  "type": "locator-map",
  "title": "New York City sights",
  "theme": "default",
  "lastEditStep": 5,
  "publishedAt": "2019-11-20T11:03:20.000Z",
  "publicUrl": "//datawrapper.dwcdn.net/1vXs6/1/",
  "publicVersion": 1,
  "deleted": false,
   ...
  "url": "/v3/charts/1vXs6"
}

Requesting a resource will most of the time return JSON objects that have an id, url and many other keys. The url key will be more important for the next section multi resource endpoints.

JSON format: Multi resource endpoints

Instead of asking the API to give us information about a single resource, we can also get information about multiples ones. With the request below, you can get a list of all the charts you've created to date: 

curl --request GET \
  --url 'https://api.datawrapper.de/v3/charts?userId=me&limit=5' \
  --header 'authorization: Bearer <YOUR_TOKEN_HERE>' \

{
  "list": [
    {
      "id": "0ee4o",
      "title": "[Untitled]",
      "type": "bar-chart",
      "createdAt": "2013-07-23T16:22:17.000Z",
      "lastModifiedAt": "2013-07-23T16:22:17.000Z",
      "publicVersion": 0,
      "url": "/v3/charts/unVrY"
    },
    {
      "id": "0eZJK",
      ...
      "url": "/v3/charts/0eZJK",
    },
    {
      "id": "20HYD",
      ...
      "url": "/v3/charts/20HYD",
    },
    {
      "id": "2L4nv",
      ...
      "url": "/v3/charts/2L4nv",
    },
    {
      "id": "4fUrE",
      ...
      "url": "/v3/charts/4fUrE",
    }
  ],
  "total": 616,
  "next": "/v3/charts?userId=me&limit=5&offset=5"
}

Multi resource endpoints have at most 3 top-level keys: list, total and next.

  • list is an array of objects. In this example we requested 5 charts.
  • total is the amount of charts that you have access to.
  • next provides the path for the next charts you might want to request. This key is only available if there are more charts.

In this response, you can see that every chart has an url key. We already know this key from single response endpoints – but this time it's a little more useful: The url key shows you the path, where to fetch more detailed information about a certain chart, user, etc.

In general, multi resource endpoints provide less information than their single resource counterparts. That makes sense: For example, when requesting /charts, you probably want an overview of your charts. But if you request to see information about just one chart, you want to learn everything about it.

CSV format

There are a few cases where a response won't return JSON. An example is the /v3/charts/<ID>/data endpoint. It will usually return CSV data – short for comma-separated values – which is a text-based format commonly used to transfer tabular data:

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

Country,"Median income (US$, PPP)[3]",mean PPP USD 2013
Ireland,22200,51681
Slovenia,16224,34965
Estonia,13719,28621
Iceland,27919,55984
United Kingdom,21576,42835

No format

Some endpoints have no response body at all. For example, if you save data for a chart, a successful response will have no body and a 204 No content status code.

You can find another example for a response with no response body when you head over to our article "Deleting a visualization".

Updated about 5 years ago