Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 44 ยท Getting Started

Loading and Parsing Data in D3

Load CSV, TSV and JSON with d3.csv, d3.tsv and d3.json, parse text with csvParse, convert types with autoType, handle errors and async/await, and reshape rows.

Charts are only as good as the data behind them. D3 ships with two small modules for that: d3-fetch loads files over HTTP, and d3-dsv parses delimiter-separated text (CSV, TSV). Together they turn a file into an array of plain objects, which is exactly what selection.data() wants. This lesson also covers the single biggest gotcha: CSV values arrive as strings.

Parsing text you already have

d3.csvParse(text) converts CSV text into an array of objects, using the first line as the keys. There is also d3.tsvParse for tabs and d3.dsvFormat(";").parse for any delimiter.

JavaScript
const rows = d3.csvParse("city,pop\nOslo,709\nBergen,291");
// [{city: "Oslo", pop: "709"}, {city: "Bergen", pop: "291"}, columns: ["city", "pop"]]

Look closely: pop is the string "709", not the number 709. CSV has no types, so D3 returns strings. The array also carries a columns property listing the headers in order.

Parsing CSV text

The "sum with strings" line prints 709291, which is string concatenation. Always convert numbers before doing math.

Converting types

There are two approaches.

Row conversion function. Pass a function as the second argument; it runs once per row and returns the cleaned object. You choose exactly which columns become numbers, dates or booleans. Returning null or undefined drops the row.

JavaScript
const rows = d3.csvParse(text, d => ({
  city: d.city,
  pop: +d.pop,
  founded: new Date(+d.founded, 0, 1)
}));

d3.autoType. A quick helper that guesses types: numbers become numbers, ISO dates become Date objects, true/false become booleans, and empty strings become null. It is handy for exploration. In production prefer an explicit conversion, because auto-guessing can misread values like zip codes ("01234" becomes 1234).

autoType and an explicit row function

The explicit version keeps the leading zero of the zip code, because you decided it is text. It also introduces d3.utcParse, covered in Number and Time Formatting.

Loading files with d3.csv, d3.tsv and d3.json

d3.csv(url, row?) fetches a file and parses it. It returns a Promise, so use await or .then.

JavaScript
const data = await d3.csv("/data/cities.csv", d3.autoType);
const geo  = await d3.json("/data/map.json");

Other loaders: d3.tsv, d3.text, d3.xml, d3.html, d3.image and d3.blob. They all use the browser's fetch, so the same rules apply: the file must be served over HTTP(S) (not opened as file://), and a file from another origin needs CORS headers from that server. A failed request (404, network error) rejects the promise, so wrap it in try/catch.

Our sandbox cannot call a server of its own, so the next example loads a CSV from a data: URL. That behaves exactly like a normal URL for d3.csv, and it is a handy way to share a snippet.

d3.csv, d3.json and error handling

Fetching local files like d3.csv("data.csv") fails when you open an HTML page by double-clicking it (file://). Run a tiny local server instead, for example npx serve or python -m http.server, and open the page over http://localhost.

Several files at once

Use Promise.all to load files in parallel and wait for all of them:

JavaScript
const [cities, countries] = await Promise.all([
  d3.csv("cities.csv", d3.autoType),
  d3.json("countries.json")
]);

Common cleaning steps

Real data is messy. Do cleaning right after loading, once, so the drawing code stays simple.

JavaScript
const clean = raw
  .map(d => ({ ...d, label: d.label.trim() }))               // tidy text
  .sort((a, b) => d3.ascending(a.date, b.date));             // order by time
  • Check Number.isNaN(+d.value) after conversion, since +"n/a" is NaN.
  • Parse dates once with d3.timeParse or d3.utcParse and keep Date objects.
  • Large files? Consider converting to JSON or using a typed format; parsing 100,000 rows of CSV is fine, a million is heavy.

D3 also writes data back: d3.csvFormat(rows) and d3.tsvFormat(rows) produce text, useful for a download button.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What type does a numeric-looking CSV column have after d3.csvParse without a conversion function?

    CSV is plain text. Unless you convert (row function or autoType), all fields stay strings.
  2. 2. Why can d3.autoType be risky for production data?

    autoType guesses. When a column that looks numeric must stay text, convert it explicitly.
  3. 3. What does d3.csv('file.csv') return?

    d3-fetch loaders are asynchronous. Use await or .then to get the data.
  4. 4. How can you load two files in parallel and wait for both?

    Promise.all starts both requests at once and resolves with an array of results in order.
  5. 5. What happens if the row function passed to d3.csv returns undefined for a row?

    Returning null or undefined from the row function filters the row out.

Summary

  • d3.csvParse, d3.tsvParse and d3.dsvFormat parse text; d3.csv, d3.tsv and d3.json load files and return Promises.
  • CSV fields are strings. Convert with a row function or d3.autoType, and prefer explicit conversion in production.
  • Handle failures with try/catch, load several files with Promise.all, and clean data once after loading.
  • Serve pages over HTTP, not file://, and expect CORS rules for other origins.

Next: Selecting Elements