The ID of the Datawrapper chart to update. This ID can be found in the Datawrapper URL or dashboard.
An array of annotation objects. Each object defines a single annotation with its properties. Required properties for each annotation are x, y, and text.
OptionalapiKey?: stringThe name of the environment variable that stores your Datawrapper API key. If not provided, the function defaults to looking for DATAWRAPPER_KEY.
OptionalreturnResponse?: booleanIf true, the function will return the full Response object from the Datawrapper API call. This can be useful for debugging or for more detailed handling of the API response. Defaults to false.
A Promise that resolves to void if returnResponse is false (default), or a Response object if returnResponse is true.
// Update annotations on a Datawrapper chart with a simple text annotation and one with an arrow.
const chartID = "myChartId";
const myAnnotations = [
{
"x": "2024/08/30 01:52",
"y": "14496235",
"text": "This is an annotation!"
},
{
"x": "2024/06/29",
"y": "15035128",
"dy": 50,
"text": "This is also some text, but with an arrow!",
"connectorLine": {
"enabled": true,
"type": "straight",
"arrowHead": "lines"
},
"mobileFallback": false
}
];
await updateAnnotationsDW(chartID, myAnnotations);
console.log(`Annotations updated for chart ${chartID}.`);
// If your Datawrapper API key is stored under a different environment variable name (e.g., `DW_API_KEY`).
const customApiKeyChartID = "anotherChartId";
const annotationsForCustomKey = [
{ x: "2024/01/01", y: "100", text: "Custom API Key Test" }
];
await updateAnnotationsDW(customApiKeyChartID, annotationsForCustomKey, { apiKey: "DW_API_KEY" });
console.log(`Annotations updated for chart ${customApiKeyChartID} using custom API key.`);
Updates annotations on a Datawrapper chart. This function allows you to programmatically add, modify, or remove text and line annotations on your Datawrapper visualizations, providing precise control over highlighting specific data points or trends.
This function supports various annotation properties, including position, text content, styling (bold, italic, color, size), alignment, and connector lines with customizable arrowheads.
Authentication is handled via an API key, which can be provided through environment variables (
DATAWRAPPER_KEY) or explicitly in the options. For detailed information on Datawrapper annotations and their properties, refer to the official Datawrapper API documentation.Annotation fields:
x: The x-coordinate of the annotation's position on the chart.y: The y-coordinate of the annotation's position on the chart.text: The text content of the annotation.bg: Iftrue, the annotation text will have a background. Defaults tofalse.dx: The horizontal offset of the annotation text from itsxcoordinate, in pixels. Defaults to0.dy: The vertical offset of the annotation text from itsycoordinate, in pixels. Defaults to0.bold: Iftrue, the annotation text will be bold. Defaults tofalse.size: The font size of the annotation text in pixels. Defaults to12.align: The alignment of the annotation text relative to itsxandycoordinates. Can be"tl"(top-left),"tc"(top-center),"tr"(top-right),"ml"(middle-left),"mc"(middle-center),"mr"(middle-right),"bl"(bottom-left),"bc"(bottom-center), or"br"(bottom-right). Defaults to"mr".color: The color of the annotation text (e.g.,"#FF0000","red"). Defaults to"#8C8C8C".width: The maximum width of the annotation text box in pixels. Text will wrap if it exceeds this width. Defaults to20.italic: Iftrue, the annotation text will be italic. Defaults tofalse.underline: Iftrue, the annotation text will be underlined. Defaults tofalse.showMobile: Iftrue, the annotation will be visible on mobile devices. Defaults totrue.showDesktop: Iftrue, the annotation will be visible on desktop devices. Defaults totrue.mobileFallback: Iftrue, the annotation will be displayed as a simple text label on mobile if it's too complex. Defaults tofalse.connectorLine: An object defining the properties of a connector line from the annotation to a data point.connectorLine.type: The type of the connector line. Can be"straight","curveRight", or"curveLeft". Defaults to"straight".connectorLine.circle: Iftrue, a circle will be drawn at the end of the connector line. Defaults tofalse.connectorLine.stroke: The stroke width of the connector line. Can be1,2, or3. Defaults to1.connectorLine.enabled: Iftrue, the connector line will be drawn. Defaults tofalse.connectorLine.arrowHead: The style of the arrowhead. Can be"lines","triangle", orfalse(no arrowhead). Defaults to"lines".connectorLine.circleStyle: The style of the circle at the end of the connector line. Defaults to"solid".connectorLine.circleRadius: The radius of the circle at the end of the connector line. Defaults to10.connectorLine.inheritColor: Iftrue, the connector line will inherit the annotation's text color. Defaults tofalse.connectorLine.targetPadding: The padding between the end of the connector line and the target data point. Defaults to4.