**Journalism Dataviz v1.0.30**

***

# The Journalism Library (dataviz)

Useful TypeScript functions for data visualization in journalism projects.
Part of the [journalism library](https://github.com/nshiab/journalism).

The library is maintained by [Nael Shiab](https://naelshiab.com/), computational
journalist and senior data producer for [CBC News](https://www.cbc.ca/news).

> [!TIP]
> To learn how to use this library and more, check out
> [Code Like a Journalist](https://www.code-like-a-journalist.com/), a free and
> open-source data analysis and data visualization course in TypeScript. You
> might also find
> [simple-data-analysis](https://github.com/nshiab/simple-data-analysis) useful.

## Installation

```sh
npm install @nshiab/journalism-dataviz
```

```ts
import { logBarChart } from "@nshiab/journalism-dataviz";

logBarChart(
  [
    { country: "Canada", count: 40 },
    { country: "France", count: 25 },
  ],
  "country",
  "count",
);
```

To start a data project with folders, configuration and documentation for AI
agents, run:

```sh
npx @nshiab/setup-data-project
```

## Browser use

For browser projects, use the `/web` entry point with a browser bundler.

```ts
import { rewind } from "@nshiab/journalism-dataviz/web";

const polygon = {
  type: "Polygon",
  coordinates: [
    [
      [0, 0],
      [1, 0],
      [1, 1],
      [0, 0],
    ],
  ],
};
const rewound = rewind(polygon);
```

## Documentation

- [Documentation](https://nshiab.github.io/journalism-dataviz/)
- [llms.txt — Documentation index for AI agents](https://nshiab.github.io/journalism-dataviz/llms.txt)
- [llm.md — Complete Markdown reference](https://nshiab.github.io/journalism-dataviz/llm.md),
  for AI assistants or offline reading
- [npm package](https://www.npmjs.com/package/@nshiab/journalism-dataviz)

See
[CONTRIBUTING.md](https://github.com/nshiab/journalism-dataviz/blob/main/CONTRIBUTING.md)
for development commands.

## Dataviz

### getDataDW()

> **getDataDW**(`chartId`, `options?`): `Promise`\<`unknown`\>

Defined in: [getDataDW.ts:43](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/getDataDW.ts#L43)

Gets the data of a Datawrapper chart, table, or map.

Authentication is handled via an API key, which can be provided through environment variables (`DATAWRAPPER_KEY`) or explicitly in the options.

#### Parameters

##### chartId

`string`

The unique ID of the Datawrapper chart, table, or map. This ID can be found in the Datawrapper URL or dashboard.

##### options?

Optional parameters to configure the request.

###### apiKey?

`string`

The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for the `DATAWRAPPER_KEY` environment variable.

###### parse?

`boolean`

If `true`, the response will be parsed and returned as a JavaScript value. CSV data (charts and tables) is returned as an array of objects; JSON data (maps) is returned as a parsed object. Defaults to `false`.

###### returnResponse?

`boolean`

If `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`.

#### Returns

`Promise`\<`unknown`\>

A Promise that resolves to a raw `string` by default, a parsed value if `parse` is `true` (`Record<string, string>[]` for CSV charts/tables, or a `object` for JSON maps), or a `Response` object if `returnResponse` is `true`.

#### Examples

```ts
import { getDataDW } from "journalism-dataviz";

const data = await getDataDW("myChartId");
console.log(data); // raw CSV string
```

```ts
// Parse a chart or table — returns an array of objects (all values are strings).
const rows = await getDataDW("myChartId", { parse: true });
console.log(rows); // [{ salary: "75000", hireDate: "2022-12-15" }, ...]
```

```ts
// Parse a locator map — detects JSON automatically and returns a parsed object.
const map = await getDataDW("myMapId", { parse: true });
console.log(map); // { type: "FeatureCollection", features: [...], markers: [] }
```

```ts
// If your API key is stored under a different name in process.env (e.g., `DW_KEY`).
const data = await getDataDW("anotherChartId", { apiKey: "DW_KEY" });
console.log(data);
```

***

### getInfoDW()

> **getInfoDW**(`chartId`, `options?`): `Promise`\<`Record`\<`string`, `unknown`\> \| `Response`\>

Defined in: [getInfoDW.ts:39](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/getInfoDW.ts#L39)

Gets information and settings for a Datawrapper chart, table, or map.

Returns the full parsed chart object, including any chart-specific fields. Property values are typed as unknown because the response varies by visualization.

Authentication is handled via an API key stored in an environment variable (`DATAWRAPPER_KEY` by default). The token requires `chart:read` or `chart:write` scope.

#### Parameters

##### chartId

`string`

The unique ID of the Datawrapper chart, table, or map. This ID can be found in the Datawrapper URL or dashboard.

##### options?

Optional parameters to configure the request.

###### apiKey?

`string`

The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for the `DATAWRAPPER_KEY` environment variable.

###### returnResponse?

`boolean`

If `true`, the function will return the full, unconsumed `Response` object from the Datawrapper API call, including HTTP error responses. This can be useful for debugging or for more detailed handling of the API response. Defaults to `false`.

#### Returns

`Promise`\<`Record`\<`string`, `unknown`\> \| `Response`\>

A Promise that resolves to a parsed `Record<string, unknown>` by default, or a `Response` object if `returnResponse` is `true`.

#### Examples

```ts
import { getInfoDW } from "@nshiab/journalism-dataviz";

const info = await getInfoDW("myChartId");
console.log(info); // full parsed chart object
```

```ts
// If your API key is stored under a different name in process.env (e.g., `DW_KEY`).
const info = await getInfoDW("anotherChartId", { apiKey: "DW_KEY" });
console.log(info);
```

```ts
// Get the full Response for more detailed handling.
const response = await getInfoDW("myChartId", { returnResponse: true });
if (response instanceof Response) {
  console.log(response.status);
}
```

***

### logBarChart()

> **logBarChart**\<`T`\>(`data`, `labels`, `values`, `options?`): `void`

Defined in: [logBarChart.ts:52](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/logBarChart.ts#L52)

Generates and logs a text-based bar chart to the console. This function is useful for quickly visualizing data distributions or comparisons directly within a terminal or log output, without needing a graphical interface. It's particularly effective for presenting categorical data or showing the relative magnitudes of different items.

The chart is constructed using ASCII characters, making it universally compatible across various terminal environments. It can display data for various categories and their corresponding numerical values, with extensive options for custom formatting of labels and values, controlling the chart's width, and adding a descriptive title or a total label. For optimal visualization, it's recommended that the input `data` be sorted by the `values` key in descending order, though the function does not enforce this.

#### Type Parameters

##### T

`T` *extends* `Record`\<`string`, `unknown`\>

#### Parameters

##### data

`T`[]

An array of objects, where each object represents a bar in the chart. Each object should contain keys corresponding to the `labels` and `values` parameters.

##### labels

keyof `T`

The key in the data objects whose values will be used as textual labels for each bar (e.g., 'category', 'name', 'country').

##### values

keyof `T`

The key in the data objects whose numerical values will determine the length of each bar and be displayed alongside the labels (e.g., 'sales', 'count', 'percentage').

##### options?

Optional configuration for customizing the appearance and behavior of the chart.

###### compact?

`boolean`

If `true`, the chart will be rendered in a more compact format, reducing vertical spacing between bars. Defaults to `false`.

###### formatLabels?

(`d`) => `string`

A function to format the labels displayed on the chart. It receives the raw label value as input and should return a string. Defaults to converting the label to a string.

###### formatValues?

(`d`) => `string`

A function to format the numerical values displayed next to the bars. It receives the numerical value as input and should return a string. Defaults to formatting the number using `formatNumber` (which adds commas for thousands, etc.).

###### showPercentages?

`boolean`

If `true`, the percentage of the total for each bar will be displayed next to its value. Defaults to `false`.

###### showTotal?

`boolean`

If `true`, the total sum of all values will be displayed above the chart. Defaults to `false`.

###### title?

`string`

An optional title to display above the chart. If not provided, a default title based on `labels` and `values` keys will be generated.

###### totalLabel?

`string`

An optional label to display for the total sum of all values at the bottom of the chart. If provided, the sum of all `values` will be calculated and displayed next to this label. This also enables the display of the total row.

###### width?

`number`

The maximum width of the bars in characters. The bars will scale proportionally to this width. A larger width allows for more detailed visualization. Defaults to `40`.

#### Returns

`void`

#### Examples

```ts
// Visualize sales data for different regions.
const salesData = [
  { region: 'North', sales: 1200 },
  { region: 'South', sales: 800 },
  { region: 'East', sales: 1500 },
  { region: 'West', sales: 950 }
];
logBarChart(salesData, 'region', 'sales', { title: 'Regional Sales Overview' });
```

```ts
// Display product popularity with custom value formatting, a compact layout, and show percentages.
const productPopularity = [
  { product: 'Laptop', views: 5000 },
  { product: 'Mouse', views: 1500 },
  { product: 'Keyboard', views: 2500 }
];
logBarChart(productPopularity, 'product', 'views', {
  formatValues: (v) => `${v / 1000}K`,
  width: 30,
  compact: true,
  totalLabel: 'Total Views',
  showPercentages: true
});
```

***

### logDotChart()

> **logDotChart**\<`T`, `X`\>(`data`, `x`, `y`, `options?`): `void`

Defined in: [logDotChart.ts:72](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/logDotChart.ts#L72)

Generates and logs a text-based dot chart to the console. This function is ideal for visualizing the relationship between two numerical variables. It provides a quick, terminal-friendly way to inspect data trends and distributions.

The chart is rendered using ASCII characters, ensuring compatibility across various terminal environments. It supports custom formatting for both x and y-axis values, and can generate small multiples to compare distributions across different categories. While the function expects data to be sorted by the x-axis values for proper rendering, it does not enforce this.

**Data Type Requirements:**
- **X-axis values**: Must be `number` or `Date` objects.
- **Y-axis values**: Must be `number` values.
- All values must be non-null and defined.

#### Type Parameters

##### T

`T` *extends* `Record`\<`string`, `unknown`\>

##### X

`X` *extends* `string` \| `number` \| `symbol` = keyof `T`

#### Parameters

##### data

`T`[]

An array of objects representing the data to be visualized. Each object should contain keys corresponding to the `x` and `y` parameters.

##### x

`X`

The key in the data objects whose values will be plotted on the x-axis. Values must be numbers or Date objects.

##### y

keyof `T`

The key in the data objects whose values will be plotted on the y-axis. Values must be numbers.

##### options?

An optional object to customize the chart's appearance and behavior.

###### fixedScales?

`boolean`

If `true` and `smallMultiples` is used, all small multiple charts will share the same x and y scales, allowing for direct comparison of magnitudes. If `false`, each small multiple will have its own independent scales. Defaults to `false`.

###### formatX?

(`d`) => `string`

A function to format the x-axis values for display. It receives the raw x-value as input and should return a string. If the first data point's x value is a Date, it defaults to formatting the date as "YYYY-MM-DD".

###### formatY?

(`d`) => `string`

A function to format the y-axis values for display. It receives the numerical y-value as input and should return a string.

###### height?

`number`

The height of the chart in lines. This affects the vertical resolution of the chart. Defaults to `20`.

###### smallMultiples?

keyof `T`

A key in the data objects to create small multiples (separate charts) for each unique value of this key. This is useful for comparing trends across different categories.

###### smallMultiplesPerRow?

`number`

The number of small multiples to display per row when `smallMultiples` is used. Defaults to `3`.

###### title?

`string`

The title of the chart. If not provided, a default title based on `x`, `y`, and `smallMultiples` (if applicable) will be generated.

###### width?

`number`

The width of the chart in characters. This affects the horizontal resolution of the chart. Defaults to `60`.

#### Returns

`void`

#### Examples

```ts
// Visualize a time series of values.
const timeSeriesData = [
    { date: new Date("2023-01-01"), value: 10 },
    { date: new Date("2023-02-01"), value: 20 },
    { date: new Date("2023-03-01"), value: 30 },
    { date: new Date("2023-04-01"), value: 40 },
];

logDotChart(timeSeriesData, "date", "value", {
    formatX: (d) => d.toISOString().slice(0, 10),
    formatY: (d) => "$" + d.toString(),
    title: "Monthly Sales Trend",
});
```

```ts
// Compare trends across different categories using small multiples.
const multiCategoryData = [
    { date: new Date("2023-01-01"), value: 10, category: "A" },
    { date: new Date("2023-02-01"), value: 20, category: "A" },
    { date: new Date("2023-03-01"), value: 30, category: "A" },
    { date: new Date("2023-04-01"), value: 40, category: "A" },
    { date: new Date("2023-01-01"), value: 15, category: "B" },
    { date: new Date("2023-02-01"), value: 25, category: "B" },
    { date: new Date("2023-03-01"), value: 35, category: "B" },
    { date: new Date("2023-04-01"), value: 45, category: "B" },
];

logDotChart(multiCategoryData, "date", "value", {
    formatX: (d) => d.toISOString().slice(0, 10),
    formatY: (d) => "$" + d.toString(),
    smallMultiples: "category",
    smallMultiplesPerRow: 2,
    fixedScales: true,
    title: "Sales Trend by Category",
});
```

***

### logLineChart()

> **logLineChart**\<`T`, `X`\>(`data`, `x`, `y`, `options?`): `void`

Defined in: [logLineChart.ts:71](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/logLineChart.ts#L71)

Generates and logs a text-based line chart to the console. This function is particularly useful for visualizing trends over time providing a quick and accessible way to understand data progression directly within a terminal or log output.

The chart is rendered using ASCII characters, ensuring broad compatibility. It supports custom formatting for both x and y-axis values, and can generate small multiples to compare trends across different categories. When the chart's width is smaller than the number of data points, the line represents an averaged approximation of the data, providing a smoothed view of the trend. For optimal visualization, it's recommended that the input `data` be sorted by the x-axis values.

**Data Type Requirements:**
- **X-axis values**: Must be `number` or `Date` objects.
- **Y-axis values**: Must be `number` values.
- All values must be non-null and defined.

#### Type Parameters

##### T

`T` *extends* `Record`\<`string`, `unknown`\>

##### X

`X` *extends* `string` \| `number` \| `symbol` = keyof `T`

#### Parameters

##### data

`T`[]

An array of objects representing the data to be visualized. Each object should contain keys corresponding to the `x` and `y` parameters.

##### x

`X`

The key in the data objects whose values will be plotted on the x-axis. Values must be numbers or Date objects.

##### y

keyof `T`

The key in the data objects whose values will be plotted on the y-axis. Values must be numbers.

##### options?

An optional object to customize the chart's appearance and behavior.

###### fixedScales?

`boolean`

If `true` and `smallMultiples` is used, all small multiple charts will share the same x and y scales, allowing for direct comparison of magnitudes. If `false`, each small multiple will have its own independent scales. Defaults to `false`.

###### formatX?

(`d`) => `string`

A function to format the x-axis values for display. It receives the raw x-value as input and should return a string. If the first data point's x value is a Date, it defaults to formatting the date as "YYYY-MM-DD".

###### formatY?

(`d`) => `string`

A function to format the y-axis values for display. It receives the numerical y-value as input and should return a string.

###### height?

`number`

The height of the chart in lines. This affects the vertical resolution of the chart. Defaults to `20`.

###### smallMultiples?

keyof `T`

A key in the data objects to create small multiples (separate charts) for each unique value of this key. This is useful for comparing trends across different categories.

###### smallMultiplesPerRow?

`number`

The number of small multiples to display per row when `smallMultiples` is used. Defaults to `3`.

###### title?

`string`

The title of the chart. If not provided, a default title based on `x`, `y`, and `smallMultiples` (if applicable) will be generated.

###### width?

`number`

The width of the chart in characters. This affects the horizontal resolution of the chart. Defaults to `60`.

#### Returns

`void`

#### Examples

```ts
// Visualize a simple time series of values.
const timeSeriesData = [
    { date: new Date("2023-01-01"), value: 10 },
    { date: new Date("2023-02-01"), value: 20 },
    { date: new Date("2023-03-01"), value: 30 },
    { date: new Date("2023-04-01"), value: 40 },
];

logLineChart(timeSeriesData, "date", "value", {
    formatX: (d) => d.toISOString().slice(0, 10),
    title: "Monthly Data Trend",
});
```

```ts
// Compare trends across different categories using small multiples.
const multiCategoryData = [
    { date: new Date("2023-01-01"), value: 10, category: "A" },
    { date: new Date("2023-02-01"), value: 20, category: "A" },
    { date: new Date("2023-03-01"), value: 30, category: "A" },
    { date: new Date("2023-04-01"), value: 40, category: "A" },
    { date: new Date("2023-01-01"), value: 15, category: "B" },
    { date: new Date("2023-02-01"), value: 25, category: "B" },
    { date: new Date("2023-03-01"), value: 35, category: "B" },
    { date: new Date("2023-04-01"), value: 45, category: "B" },
];

logLineChart(multiCategoryData, "date", "value", {
    formatX: (d) => d.toLocaleDateString(),
    formatY: (d) => "$" + d.toString(),
    smallMultiples: "category",
    smallMultiplesPerRow: 2,
    fixedScales: true,
    title: "Sales Trend by Category",
});
```

***

### publishChartDW()

> **publishChartDW**(`chartId`, `options?`): `Promise`\<`void` \| `Response`\>

Defined in: [publishChartDW.ts:35](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/publishChartDW.ts#L35)

Publishes a specified Datawrapper chart, table, or map. This function streamlines the process of making your Datawrapper visualizations live, allowing for automated deployment and updates. It handles authentication using an API key, which can be provided via environment variables or directly through options.

#### Parameters

##### chartId

`string`

The unique ID of the Datawrapper chart, table, or map to be published. This ID can be found in the Datawrapper URL or dashboard.

##### options?

Optional parameters to configure the publishing process.

###### apiKey?

`string`

The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for the `DATAWRAPPER_KEY` environment variable.

###### returnResponse?

`boolean`

If `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`.

#### Returns

`Promise`\<`void` \| `Response`\>

A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.

#### Examples

```ts
// Publish a Datawrapper chart with a given ID.
const chartID = "myChartId";
await publishChartDW(chartID);
console.log(`Chart ${chartID} published successfully.`);
```

```ts
// If your Datawrapper API key is stored under a different environment variable name (e.g., `DW_API_KEY`).
const customApiKeyChartID = "anotherChartId";
await publishChartDW(customApiKeyChartID, { apiKey: "DW_API_KEY" });
console.log(`Chart ${customApiKeyChartID} published using custom API key.`);
```

```ts
// Get the full HTTP response object after publishing.
const chartIDForResponse = "yetAnotherChartId";
const response = await publishChartDW(chartIDForResponse, { returnResponse: true });
console.log(`Response status for ${chartIDForResponse}: ${response?.status}`);
```

***

### rewind()

> **rewind**\<`T`\>(`object`): `T`

Defined in: [rewind.ts:105](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/rewind.ts#L105)

Rewinds the winding order of the specified GeoJSON object to be clockwise. It is based on the D3-geo library's winding order conventions.

#### Type Parameters

##### T

`T`

#### Parameters

##### object

`T`

A GeoJSON geometry, feature, feature collection, or null.

#### Returns

`T`

A rewound copy; non-polygon geometries are returned unchanged. Polygon coordinates are two-dimensional.

#### Examples

```ts
// Rewind a FeatureCollection.
const featureCollection = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: {},
      geometry: {
        type: "Polygon",
        coordinates: [[[-10, -10], [-10, 10], [10, 10], [10, -10], [-10, -10]]]
      }
    }
  ]
};
const rewoundFeatureCollection = rewind(featureCollection);
```

```ts
// Rewind a GeoJSON Feature containing a Polygon geometry.
const feature = {
  type: "Feature",
  properties: { name: "Example Area" },
  geometry: {
    type: "Polygon",
    coordinates: [[[-5, -5], [-5, 5], [5, 5], [5, -5], [-5, -5]]]
  }
};
const rewoundFeature = rewind(feature);
console.log(rewoundFeature);
```

***

### saveChart()

> **saveChart**\<`T`\>(`data`, `chart`, `path`, `options?`): `Promise`\<`void`\>

Defined in: [saveChart.ts:53](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/saveChart.ts#L53)

Saves an [Observable Plot](https://github.com/observablehq/plot) chart or map as a PNG or SVG file.
The chart function can return an SVG or HTML element directly or through a promise.
The rendering environment remains available until the chart function finishes.
Concurrent saves are processed one at a time to protect that environment.
Calling `saveChart` from inside its own chart function is not supported and rejects with an error.

#### Type Parameters

##### T

`T`

The type of data passed unchanged to the chart function.

#### Parameters

##### data

`T`

The data passed to the chart function.

##### chart

(`data`) => `SVGSVGElement` \| `HTMLElement` \| `Promise`\<`SVGSVGElement` \| `HTMLElement`\>

A synchronous or asynchronous function returning an SVG or HTML element representing the chart or map.

##### path

`string`

The output file path. The extension must be `.png` or `.svg`.

##### options?

Optional settings to customize the chart's appearance.

###### dark?

`boolean`

If `true`, renders the chart with a dark theme. Defaults to `false`.

###### style?

`string`

A CSS string inserted into the generated SVG.

#### Returns

`Promise`\<`void`\>

A promise that resolves after the file has been saved, or rejects if the chart function or saving fails.

#### Examples

```ts
import { dot, plot } from "@observablehq/plot";

const data = [{ year: 2024, value: 10 }, { year: 2025, value: 15 }];
await saveChart(
  data,
  (rows) => plot({ marks: [dot(rows, { x: "year", y: "value" })] }),
  "output/chart.png",
);
```

```ts
// Load Observable Plot asynchronously before creating the chart.
const data = [{ year: 2024, value: 10 }, { year: 2025, value: 15 }];
await saveChart(
  data,
  async (rows) => {
    const { dot, plot } = await import("@observablehq/plot");
    return plot({ marks: [dot(rows, { x: "year", y: "value" })] });
  },
  "output/chart.svg",
  { dark: true, style: ".chart-title { font-size: 24px; }" },
);
```

***

### updateAnnotationsDW()

> **updateAnnotationsDW**(`chartId`, `annotations`, `options?`): `Promise`\<`void` \| `Response`\>

Defined in: [updateAnnotationsDW.ts:84](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/updateAnnotationsDW.ts#L84)

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`: If `true`, the annotation text will have a background. Defaults to `false`.
- `dx`: The horizontal offset of the annotation text from its `x` coordinate, in pixels. Defaults to `0`.
- `dy`: The vertical offset of the annotation text from its `y` coordinate, in pixels. Defaults to `0`.
- `bold`: If `true`, the annotation text will be bold. Defaults to `false`.
- `size`: The font size of the annotation text in pixels. Defaults to `12`.
- `align`: The alignment of the annotation text relative to its `x` and `y` coordinates. 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 to `20`.
- `italic`: If `true`, the annotation text will be italic. Defaults to `false`.
- `underline`: If `true`, the annotation text will be underlined. Defaults to `false`.
- `showMobile`: If `true`, the annotation will be visible on mobile devices. Defaults to `true`.
- `showDesktop`: If `true`, the annotation will be visible on desktop devices. Defaults to `true`.
- `mobileFallback`: If `true`, the annotation will be displayed as a simple text label on mobile if it's too complex. Defaults to `false`.
- `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`: If `true`, a circle will be drawn at the end of the connector line. Defaults to `false`.
- `connectorLine.stroke`: The stroke width of the connector line. Can be `1`, `2`, or `3`. Defaults to `1`.
- `connectorLine.enabled`: If `true`, the connector line will be drawn. Defaults to `false`.
- `connectorLine.arrowHead`: The style of the arrowhead. Can be `"lines"`, `"triangle"`, or `false` (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 to `10`.
- `connectorLine.inheritColor`: If `true`, the connector line will inherit the annotation's text color. Defaults to `false`.
- `connectorLine.targetPadding`: The padding between the end of the connector line and the target data point. Defaults to `4`.

#### Parameters

##### chartId

`string`

The ID of the Datawrapper chart to update. This ID can be found in the Datawrapper URL or dashboard.

##### annotations

`object`[]

An array of annotation objects. Each object defines a single annotation with its properties. Required properties for each annotation are `x`, `y`, and `text`.

##### options?

###### apiKey?

`string`

The name of the environment variable that stores your Datawrapper API key. If not provided, the function defaults to looking for `DATAWRAPPER_KEY`.

###### returnResponse?

`boolean`

If `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`.

#### Returns

`Promise`\<`void` \| `Response`\>

A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.

#### Examples

```ts
// 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}.`);
```

```ts
// 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.`);
```

***

### updateDataDW()

> **updateDataDW**(`chartId`, `data`, `options?`): `Promise`\<`void` \| `Response`\>

Defined in: [updateDataDW.ts:126](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/updateDataDW.ts#L126)

Updates the data of a specified Datawrapper chart, table, or map. This function is essential for keeping your Datawrapper visualizations dynamic and up-to-date with the latest information. It supports both CSV data for standard charts and tables, and JSON data for more complex visualizations like locator maps.

Datawrapper is a powerful tool for creating interactive data visualizations. This function allows for programmatic updates, which is ideal for automated data pipelines, dashboards, or applications that require fresh data to be reflected in visualizations without manual intervention.

Authentication is handled via an API key, which can be provided through environment variables (`process.env.DATAWRAPPER_KEY`) or explicitly in the options. The `Content-Type` header for the API request is automatically set based on whether the data is CSV or JSON.

#### Parameters

##### chartId

`string`

The unique ID of the Datawrapper chart, table, or map to update. This ID can be found in the Datawrapper URL or dashboard.

##### data

`string`

The data to update the chart, table, or map with. For standard charts and tables, this should be a CSV formatted string. For locator maps, this should be a JSON string representing the map's data (e.g., markers, areas).

##### options?

Optional parameters to configure the data update process.

###### apiKey?

`string`

The name of the environment variable that stores your Datawrapper API key (e.g., `"DATAWRAPPER_KEY"`). If not provided, the function defaults to looking for `process.env.DATAWRAPPER_KEY`.

###### returnResponse?

`boolean`

If `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`.

#### Returns

`Promise`\<`void` \| `Response`\>

A Promise that resolves to `void` if `returnResponse` is `false` (default), or a `Response` object if `returnResponse` is `true`.

#### Examples

```ts
// Update the data of a Datawrapper chart or table with CSV formatted data.
import { updateDataDW, dataAsCsv } from "journalism";

const chartID = "myChartId";
const data = [
 { salary: 75000, hireDate: new Date("2022-12-15") },
 { salary: 80000, hireDate: new Date("2023-01-20") },
];
const dataForChart = dataAsCsv(data);

await updateDataDW(chartID, dataForChart);
console.log(`Data updated for chart ${chartID}.`);
```

```ts
// Update the data of a Datawrapper locator map with GeoJSON data.

const mapID = "myMapId";
const geojson = {
 "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [
              11.127454320325711,
              20.34856592751224
            ],
            [
              11.127454320325711,
              -13.781306861158996
            ],
            [
              55.68071875381875,
              -13.781306861158996
            ],
            [
              55.68071875381875,
              20.34856592751224
            ],
            [
              11.127454320325711,
              20.34856592751224
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  ]
};

const dataForMap = {
  "markers": [
    {
      "id": "m1",
      "type": "area",
      "visible": true,
      "exactShape": true,
      "fill": true,
      "stroke": true,
      "properties": {
        "fill": "#15607a",
        "fill-opacity": 0.2,
        "stroke": "#15607a",
        "stroke-width": 1,
        "stroke-opacity": 1,
        "stroke-dasharray": "100000",
        "pattern": "solid",
        "pattern-line-width": 2,
        "pattern-line-gap": 2
      },
      "feature": geojson
    }
  ]
};

await updateDataDW(mapID, JSON.stringify(dataForMap));
console.log(`Data updated for map ${mapID}.`);
```

```ts
// If your API key is stored under a different name in process.env, use the options.
const chartIDCustomKey = "anotherChartId";
const dataForCustomKey = "col1,col2\nval1,val2";
await updateDataDW(chartIDCustomKey, dataForCustomKey, { apiKey: "DW_KEY" });
console.log(`Data updated for chart ${chartIDCustomKey} using custom API key.`);
```

```ts
// Attempting to update data without a configured API key will throw an error.
try {
  await updateDataDW("someChartId", "data", { apiKey: "NON_EXISTENT_KEY" });
} catch (error) {
  console.error("Error:", error.message);
  // Expected output: "Error: process.env.NON_EXISTENT_KEY is undefined or ''"
}
```

#### Throws

If the API key is not found, if the Datawrapper API returns an error status (e.g., invalid chart ID, authentication failure, malformed data), or if there's a network issue.

***

### updateInfoDW()

> **updateInfoDW**(`chartId`, `metadata`, `options?`): `Promise`\<`void` \| `Response`\>

Defined in: [updateInfoDW.ts:47](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/updateInfoDW.ts#L47)

Updates the title, description, and notes of a Datawrapper chart, table, or map in one API request.

Only supplied fields are updated. Omit a field or pass `undefined` to preserve its existing value; pass an empty string to clear it. At least one field must be supplied. Other chart settings are preserved by Datawrapper's partial metadata update.

The API key is read from `DATAWRAPPER_KEY` by default. This function updates the draft visualization; call `publishChartDW()` afterward to publish the changes.

#### Parameters

##### chartId

`string`

The ID of the Datawrapper chart, table, or map to update.

##### metadata

The fields to update. At least one must be supplied.

###### description?

`string`

The description below the title, stored as `metadata.describe.intro`. An empty string clears it.

###### note?

`string`

The notes in the visualization's footer, stored as `metadata.annotate.notes`. An empty string clears them.

###### title?

`string`

The visualization's headline. An empty string clears it.

##### options?

Optional authentication and response settings.

###### apiKey?

`string`

The name of the environment variable containing the API key. Defaults to `"DATAWRAPPER_KEY"`.

###### returnResponse?

`boolean`

If `true`, returns the unconsumed response without checking its status. Defaults to `false`.

#### Returns

`Promise`\<`void` \| `Response`\>

A promise resolving to `void`, or to the raw `Response` when requested. By default, non-200 responses throw an error.

#### Examples

```ts
import { updateInfoDW } from "@nshiab/journalism-dataviz";

await updateInfoDW("abcde", {
  title: "Sales keep rising",
  description: "Monthly revenue since January 2025.",
  note: "Source: company filings.",
});
```

```ts
// Clear the notes while preserving the title and description.
await updateInfoDW("abcde", { note: "" }, { apiKey: "DW_KEY" });
```

```ts
// Inspect the raw response, including non-200 responses.
const response = await updateInfoDW("abcde", { title: "New title" }, {
  returnResponse: true,
});
console.log(response?.status);
```

***

### ~~updateNotesDW()~~

> **updateNotesDW**(`chartId`, `note`, `options?`): `Promise`\<`void` \| `Response`\>

Defined in: [updateNotesDW.ts:30](https://github.com/nshiab/journalism-dataviz/blob/v1.0.30/src/dataviz/updateNotesDW.ts#L30)

Updates the notes field of a Datawrapper chart, table, or map.

This function delegates to `updateInfoDW()` and logs a deprecation warning once per module instance. Use `updateInfoDW(chartId, { note }, options)` instead.

#### Parameters

##### chartId

`string`

The ID of the Datawrapper chart, table, or map to update.

##### note

`string`

The notes text. An empty string clears the notes.

##### options?

Optional authentication and response settings.

###### apiKey?

`string`

The name of the environment variable containing the API key. Defaults to `"DATAWRAPPER_KEY"`.

###### returnResponse?

`boolean`

If `true`, returns the unconsumed response without checking its status. Defaults to `false`.

#### Returns

`Promise`\<`void` \| `Response`\>

A promise resolving to `void`, or to the raw `Response` when requested. By default, non-200 responses throw an error.

#### Example

```ts
// Existing calls still work, but emit a deprecation warning.
await updateNotesDW("abcde", "Last updated today.");

// Preferred replacement, including a custom API-key environment variable.
await updateInfoDW("abcde", { note: "Last updated today." }, {
  apiKey: "DW_KEY",
});
```

#### Deprecated

Use `updateInfoDW(chartId, { note }, options)` instead. This function will be removed in the next major version.
