D3.js - Requests API

D3.js - Data Loading (Fetch API)

Visualizations are data-driven. D3.js provides convenient methods for loading external data, such as CSV, TSV, JSON, and plain text files. Modern D3 uses the d3-fetch module, which is built on the browser’s standard Fetch API and utilizes Promises for asynchronous operations. This replaces the older d3-request module.

Using d3-fetch

The d3-fetch module is included in the main D3 bundle. If you are using D3 modules separately, you can install d3-fetch.

<!-- Include the full D3 library (includes d3-fetch) -->
<script src="https://d3js.org/d3.v7.min.js"></script>

<script>
  // Example: Loading a JSON file
  // d3.json("/path/to/data.json")
  //   .then(data => {
  //     console.log(data);
  //   })
  //   .catch(error => {
  //     console.error("Error loading data:", error);
  //   });
</script>

The d3-fetch methods return Promises, which makes handling asynchronous data loading cleaner and more robust. You can use .then() for successful responses, .catch() for errors, or async/await syntax.

d3-fetch API Methods

Here are the primary methods provided by d3-fetch:

• d3.blob(url[, init]) − Fetches the file at the specified url as a Blob. init is an optional object with fetch options (e.g., headers, method).
• d3.buffer(url[, init]) − Fetches the file at url as an ArrayBuffer.
• d3.csv(url[, initOrRowConverter[, rowConverter]]) − Fetches the CSV file at url, parses it, and returns a Promise resolving to an array of objects. An optional rowConverter function can be provided to transform each row. If two functions are provided, the second is the row converter, and the first is the init object. d3.autoType is commonly used as a row converter for automatic type inference.
• d3.dsv(delimiter, url[, initOrRowConverter[, rowConverter]]) − Fetches a delimiter-separated values file (e.g., using ’;’ or ’|’) at url.
• d3.html(url[, init]) − Fetches the HTML file at url and returns a Promise resolving to a document fragment.
• d3.image(url[, init]) − Fetches the image at url and returns a Promise resolving to an HTMLImageElement. init can include crossOrigin property.
• d3.json(url[, init]) − Fetches the JSON file at url and returns a Promise resolving to the parsed JSON object.
• d3.svg(url[, init]) − Fetches the SVG file at url and returns a Promise resolving to a document fragment containing the SVG.
• d3.text(url[, init]) − Fetches the plain text file at url.
• d3.tsv(url[, initOrRowConverter[, rowConverter]]) − Fetches the TSV (tab-separated values) file at url. Similar to d3.csv.

Example: Loading and Parsing a CSV File

Let’s create sample.csv in your project folder:

product,category,price
Apple,Fruit,1.2
Banana,Fruit,0.8
Carrot,Vegetable,0.5

Now, create an HTML file to load and display this data:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>D3.js Fetch CSV Example</title>
  <script src="https://d3js.org/d3.v7.min.js"></script>
</head>
<body>
  <h3>Loaded CSV Data:</h3>
  <div id="output"></div>

  <script>
    async function loadData() {
      try {
        // Use d3.autoType to automatically convert strings to numbers, dates etc.
        const data = await d3.csv("sample.csv", d3.autoType);

        console.log(data);
        // data will be:
        // [
        //   {product: "Apple", category: "Fruit", price: 1.2},
        //   {product: "Banana", category: "Fruit", price: 0.8},
        //   {product: "Carrot", category: "Vegetable", price: 0.5}
        // ]

        const outputDiv = d3.select("#output");
        outputDiv.selectAll("p")
          .data(data)
          .join("p")
          .text(d => `Product: ${d.product}, Category: ${d.category}, Price: $${d.price.toFixed(2)}`);

      } catch (error) {
        console.error("Error loading or parsing CSV:", error);
        d3.select("#output").text("Failed to load data.");
      }
    }

    loadData();
  </script>
</body>
</html>

This example uses async/await for cleaner asynchronous code. d3.autoType is a convenient row conversion function that infers data types for columns (e.g., converting ‘1.2’ to the number 1.2).

Custom Row Conversion

For more complex data, you might need a custom row conversion function:

d3.csv("timeseries.csv", (d) => {
  return {
    date: new Date(d.timestamp), // Assuming 'timestamp' column
    value: +d.measurement // Convert 'measurement' to a number
  };
}).then(data => {
  console.log("Custom parsed data:", data);
}).catch(error => {
  console.error("Error:", error);
});

Practical Applications

Data loading is the first step in most D3.js projects:

• Fetching datasets for charts and graphs.
• Loading GeoJSON for maps.
• Retrieving configuration files or textual content.
• Loading images or SVG assets dynamically.

Always handle potential errors during data fetching using .catch() or try...catch with async/await. For further details, refer to the d3-fetch documentation.