API Reference

API Reference#

This is the class and function reference of Datawrapper, and the following content is generated automatically from the code documentation strings. Please refer to the full user guide for further details, as this low-level documentation may not be enough to give full guidelines on their use.

Modules#

class datawrapper.Datawrapper(access_token=None)[source]#

Handles connecting with Datawrapper’s API.

Handles access to your Datawrapper’s account, create, delete and move charts, tables: or maps.

Will attempt to read environment variable DATAWRAPPER_ACCESS_TOKEN by default.

Parameters:

access_token – A personal access token to use the API.
app.datawrapper.de/account/api-tokens. (See) –

account_info() → dict[Any, Any] | None | Any[source]#

Access your account information.

Returns:: A dictionary containing your account information.
Return type:: dict

add_data(chart_id: str, data: pandas.core.frame.DataFrame | str) → Response[source]#

Add data to a specified chart.

Parameters:

chart_id (str) – ID of chart, table or map to add data to.
data (pd.DataFrame | str) – A pandas dataframe containing the data to be added or a string that contains the data.

Returns:

A requests.Response

Return type:

requests.Response

chart_data(chart_id: str)[source]#

Retrieve the data stored for a specific chart, table or map, which is typically CSV.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: A dictionary containing the information of the chart, table, or map.
Return type:: dict

chart_properties(chart_id: str) → Union[dict[Any, Any], None, Any, Iterable[Any]][source]#

Retrieve information of a specific chart, table or map.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: A dictionary containing the information of the chart, table, or map.
Return type:: dict

copy_chart(chart_id: str) → dict[Any, Any][source]#

Copy one of your charts, tables, or maps and create a new editable copy.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: A dictionary containing the information of the chart, table, or map.
Return type:: dict

create_chart(title: str = 'New Chart', chart_type: str = 'd3-bars-stacked', data: pandas.core.frame.DataFrame | str | None = None, folder_id: str = '', organization_id: str = '', metadata: dict[Any, Any] | None = None) → dict[Any, Any] | None | Any[source]#

Creates a new Datawrapper chart, table or map.

You can pass a pandas DataFrame as a data argument to upload data.

Returns the created chart’s information.

Parameters:

title (str, optional) – Title for new chart, table or map, by default “New Chart”
chart_type (str, optional) – Chart type to be created. See https://developer.datawrapper.de/docs/chart-types, by default “d3-bars-stacked”
data ([type], optional) – A pandas DataFrame or string containing the data to be added, by default None
folder_id (str, optional) – ID of folder in Datawrapper.de for the chart, table or map to be created in, by default “”
organization_id (str, optional) – ID of the team where the chart should be created. The authenticated user must have access to this team.
metadata (dict, optional) – A Python dictionary of properties to add.

Returns:

A dictionary containing the created chart’s information.

Return type:

dict

create_folder(name: str, parent_id: str | int | None = None, team_id: str | int | None = None) → dict[Any, Any][source]#

Create a new folder.

Parameters:

name (str) – Name of the folder to be created.
parent_id (str | int, optional) – The parent folder that the folder belongs to.
team_id (str | int, optional) – The team that the folder belongs to. If teamId is empty, the folder will belong to the user directly.

Returns:

A dictionary containing the folder’s information.

Return type:

dict

delete_chart(chart_id: str) → <property object at 0x7f9332c3a2a0>[source]#

Deletes a specified chart, table or map.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: The content of the requests.delete
Return type:: r.Response.content

delete_folder(folder_id: str | int)[source]#

Delete an existing folder.

Parameters:: folder_id (str | int) – ID of folder to delete.
Returns:: The content of the requests.delete
Return type:: r.Response.content

display_chart(chart_id: str) → HTML[source]#

Displays a datawrapper chart.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: HTML displaying the chart.
Return type:: IPython.display.HTML

export_chart(chart_id: str, unit: str = 'px', mode: str = 'rgb', width: int = 400, plain: bool = False, zoom: int = 2, scale: int = 1, border_width: int = 20, transparent: bool = False, output: str = 'png', filepath: str = './image.png', display: bool = False) → Any | None[source]#

Exports a chart, table, or map.

Parameters:

chart_id (str) – ID of chart, table, or map.
unit (str, optional) – One of px, mm, inch. Defines the unit in which the borderwidth, height, and width will be measured in, by default “px”
mode (str, optional) – One of rgb or cmyk. Which color mode the output should be in, by default “rgb”
width (int, optional) – Width of visualization. If not specified, it takes the chart width, by default None
plain (bool, optional) –

Defines if only the visualization should be exported (True), or if it should
include header and footer as well (False), by default False
zoom (int, optional) – Defines the multiplier for the png size, by default 2
scale (int, optional) – Defines the multiplier for the pdf size, by default 1
border_width (int, optional) – Margin arouund the visualization, by default 20
transparent (bool, optional) – Set to True to export your visualization with a transparent background.
output (str, optional) – One of png, pdf, or svg, by default “png”
filepath (str, optional) – Name/filepath to save output in, by default “./image.png”
display (bool, optional) – Whether to display the exported image as output in the notebook cell, by default False
None (Returns) –
------- –
IPython.display.Image – If display is True, it returns an Image.

fork_chart(chart_id: str) → dict[Any, Any][source]#

Fork a chart, table, or map and create an editable copy.

Parameters:: chart_id (str) – ID of chart, table, or map.
Returns:: A dictionary containing the information of the chart, table, or map.
Return type:: dict

get_charts(user_id: str = '', published: str = 'true', search: str = '', order: str = 'DESC', order_by: str = 'createdAt', limit: int = 25, folder_id: str = '', team_id: str = '') → None | list[Any][source]#

Retrieves a list of charts by User

Parameters:

user_id (str, optional) – ID of the user to fetch charts for, by default “”
published (str, optional) – Flag to filter resutls by publish status, by default “true”
search (str, optional) – Search for charts with a specific title, by default “”
order (str, optional) – Result order (ascending or descending), by default “DESC”
order_by (str, optional) – Attribute to order by. One of createdAt, email, id, or name, by default “createdAt”
limit (int, optional) – Maximum items to fetch, by default 25
folder_id (str, optional) – ID of folder in Datawrapper.de where to list charts, by default “”
team_id (str, optional) – ID of the team where to list charts. The authenticated user must have access to this team, by default “”

Returns:

List of charts.

Return type:

list

get_folder(folder_id: str | int) → dict[Any, Any][source]#

Get an existing folder.

Parameters:: folder_id (str | int) – ID of folder to get.
Returns:: A dictionary containing the folder’s information.
Return type:: dict

get_folders() → dict[Any, Any] | None | Any[source]#

Get a list of folders in your Datawrapper account.

Returns:: A dictionary containing the folders in your Datawrapper account and their information.
Return type:: dict

get_iframe_code(chart_id: str, responsive: bool = False) → str | Any[source]#

Returns a chart, table, or map’s iframe embed code.

Parameters:

chart_id (str) – ID of chart, table, or map.
responsive (bool, optional) – Whether to return a responsive iframe embed code., by default False

Returns:

iframe embed code.

Return type:

str

move_chart(chart_id: str, folder_id: str) → Any | None[source]#

Moves a chart, table, or map to a specified folder.

Parameters:

chart_id (str) – ID of chart, table, or map.
folder_id (str) – ID of folder to move visualization to.

publish_chart(chart_id: str, display: bool = True) → Any | None[source]#

Publishes a chart, table or map.

Parameters:

chart_id (str) – ID of chart, table or map.
display (bool, optional) – Display the published chart as output in notebook cell, by default True

refresh_data(chart_id: str) → Response[source]#

Fetch configured external data and add it to the chart.

Parameters:: chart_id (str) – ID of chart, table or map to add data to.
Returns:: A requests.Response
Return type:: requests.Response

update_chart(chart_id: str, title: str = '', theme: str = '', chart_type: str = '', language: str = '', folder_id: str = '', organization_id: str = '') → Any | None[source]#

Updates a chart’s title, theme, type, language, or location (folder/organization).

Parameters:

chart_id (str) – ID Of chart, table, or map.
title (str, optional) – New title, by default “”
theme (str, optional) – New theme, by default “”
chart_type (str, optional) – New chart type. See https://developer.datawrapper.de/docs/chart-types, by default “”
language (str, optional) – New language, by default “”
folder_id (str, optional) – New folder’s ID, by default “”
organization_id (str, optional) – New organization’s ID, by default “”

update_description(chart_id: str, source_name: str = '', source_url: str = '', intro: str = '', byline: str = '', aria_description: str = '', number_prepend: str = '', number_append: str = '', number_format: str = '-', number_divisor: int = 0) → Any | None[source]#

Update a chart’s description.

Parameters:

chart_id (str) – ID of chart, table or map.
source_name (str, optional) – Source of data, by default “”
source_url (str, optional) – URL of source of data, by default “”
intro (str, optional) – Introduction of your chart, table or map, by default “”
byline (str, optional) – Who made this?, by default “”
aria_description (str, optional) – Alt text description
number_prepend (str, optional) – Something to put before the number
number_append (str, optional) – Something to after before the number
number_format (str, optional) – The format number
number_divisor (str, optional) – A multiplier or divisor for the numbers

Update an existing folder.

Parameters:

folder_id (str | int) – ID of folder to update.
name (str, optional) – Name to change the folder to.
parent_id (str | int, optional) – The parent folder where this folder is stored.
team_id (str | int, optional) – The team that the folder belongs to.
user_id (str | int, optional) – The user that the folder belongs to.

Returns:

The content of the requests.delete

Return type:

r.Response.content

update_metadata(chart_id: str, properties: dict[Any, Any]) → Any | None[source]#

Update a chart, table, or map’s metadata.

Example: https://developer.datawrapper.de/docs/creating-a-chart-new#edit-colors

Parameters:

chart_id (str) – ID of chart, table, or map.
properties (dict) – A python dictionary of properties to update.

API Reference

Contents

API Reference#

Modules#