d3-fetch

What is d3-fetch?

The d3-fetch module provides a convenient way to fetch resources asynchronously, such as text files, JSON data, and binary files, using promises. It is part of the D3.js library, which is widely used for data visualization. d3-fetch simplifies the process of loading external data into your web applications, making it easier to integrate and manipulate this data within your D3 visualizations.

What are d3-fetch's main functionalities?

Fetching Text Files

This feature allows you to fetch and read text files. The code sample demonstrates how to load a text file and log its contents to the console.

d3.text('path/to/your/file.txt').then(function(data) { console.log(data); });

Fetching JSON Data

This feature enables you to fetch and parse JSON data. The code sample shows how to load JSON data and log it to the console, making it easy to integrate into your visualizations or data processing logic.

d3.json('path/to/your/data.json').then(function(data) { console.log(data); });

Fetching Binary Files

This feature is used for fetching binary files, such as images or other binary data. The code sample demonstrates how to load a binary file and log the Blob object to the console.

d3.blob('path/to/your/file.bin').then(function(blob) { console.log(blob); });

Other packages similar to d3-fetch

axios

Axios is a popular HTTP client for the browser and node.js. It provides a simple to use API for making XMLHttpRequests from the browser or HTTP requests from node.js. Compared to d3-fetch, axios offers a wider range of features, including intercepting requests and responses, transforming request and response data, and automatic transforms for JSON data. However, it is not specifically designed for integrating with D3 visualizations.

fetch-json

fetch-json is a lightweight wrapper around the Fetch API, designed to simplify fetching and posting JSON data. It provides a more focused API for JSON operations compared to d3-fetch, but lacks the broader file type support found in d3-fetch, such as text and binary file fetching.

README

d3-fetch

This module provides convenient parsing on top of Fetch. For example, to load a text file:

const text = await d3.text("/path/to/file.txt");
console.log(text); // Hello, world!

To load and parse a CSV file:

const data = await d3.csv("/path/to/file.csv");
console.log(data); // [{"Hello": "world"}, …]

This module has built-in support for parsing JSON, CSV, and TSV. You can parse additional formats by using text directly. (This module replaced d3-request.)

Installing

If you use npm, npm install d3-fetch. You can also download the latest release on GitHub. For vanilla HTML in modern browsers, import d3-fetch from Skypack:

<script type="module">

import {csv} from "https://cdn.skypack.dev/d3-fetch@3";

csv("/path/to/file.csv").then((data) => {
  console.log(data); // [{"Hello": "world"}, …]
});

</script>

For legacy environments, you can load d3-fetch’s UMD bundle from an npm-based CDN such as jsDelivr; a d3 global is exported:

<script src="https://cdn.jsdelivr.net/npm/d3-fetch@3"></script>
<script>

d3.csv("/path/to/file.csv").then((data) => {
  console.log(data); // [{"Hello": "world"}, …]
});

</script>

API Reference

# d3.blob(input[, init]) · Source

Fetches the binary file at the specified input URL as a Blob. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.

# d3.buffer(input[, init]) · Source

Fetches the binary file at the specified input URL as an ArrayBuffer. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.

# d3.csv(input[, init][, row]) · Source

Equivalent to d3.dsv with the comma character as the delimiter.

# d3.dsv(delimiter, input[, init][, row]) · Source

Fetches the DSV file at the specified input URL. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields. An optional row conversion function may be specified to map and filter row objects to a more-specific representation; see dsv.parse for details. For example:

const data = await d3.dsv(",", "test.csv", (d) => {
  return {
    year: new Date(+d.Year, 0, 1), // convert "Year" column to Date
    make: d.Make,
    model: d.Model,
    length: +d.Length // convert "Length" column to number
  };
});

If only one of init and row is specified, it is interpreted as the row conversion function if it is a function, and otherwise an init object.

See also d3.csv and d3.tsv.

# d3.html(input[, init]) · Source

Fetches the file at the specified input URL as text and then parses it as HTML. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.

# d3.image(input[, init]) · Source

Fetches the image at the specified input URL. If init is specified, sets any additional properties on the image before loading. For example, to enable an anonymous cross-origin request:

const img = await d3.image("https://example.com/test.png", {crossOrigin: "anonymous"});

# d3.json(input[, init]) · Source

Fetches the JSON file at the specified input URL. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields. If the server returns a status code of 204 No Content or 205 Reset Content, the promise resolves to undefined.

# d3.svg(input[, init]) · Source

Fetches the file at the specified input URL as text and then parses it as SVG. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.

# d3.text(input[, init]) · Source

Fetches the text file at the specified input URL. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.

# d3.tsv(input[, init][, row]) · Source

Equivalent to d3.dsv with the tab character as the delimiter.

# d3.xml(input[, init]) · Source

Fetches the file at the specified input URL as text and then parses it as XML. If init is specified, it is passed along to the underlying call to fetch; see RequestInit for allowed fields.