d3-request

What is d3-request?

The d3-request npm package is a part of the D3.js library and is used for making HTTP requests. It provides a simple API for fetching data from a server, which is particularly useful for loading data in various formats such as JSON, CSV, and XML for data visualization purposes.

What are d3-request's main functionalities?

Fetching JSON Data

This feature allows you to fetch JSON data from a specified URL. The callback function handles the response, where you can process the data or handle errors.

const d3 = require('d3-request');
d3.json('https://api.example.com/data', function(error, data) {
  if (error) throw error;
  console.log(data);
});

Fetching CSV Data

This feature allows you to fetch CSV data from a specified URL. The callback function processes the CSV data into an array of objects.

const d3 = require('d3-request');
d3.csv('https://api.example.com/data.csv', function(error, data) {
  if (error) throw error;
  console.log(data);
});

Fetching XML Data

This feature allows you to fetch XML data from a specified URL. The callback function processes the XML data, which can then be manipulated as needed.

const d3 = require('d3-request');
d3.xml('https://api.example.com/data.xml', function(error, data) {
  if (error) throw error;
  console.log(data);
});

Fetching Text Data

This feature allows you to fetch plain text data from a specified URL. The callback function handles the text response.

const d3 = require('d3-request');
d3.text('https://api.example.com/data.txt', function(error, data) {
  if (error) throw error;
  console.log(data);
});

Other packages similar to d3-request

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a more modern and flexible API compared to d3-request, supporting features like interceptors, automatic JSON transformation, and request cancellation.

node-fetch

Node-fetch is a lightweight module that brings `window.fetch` to Node.js. It is a more modern alternative to d3-request, providing a simple and consistent API for making HTTP requests.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with a flexible API. It offers more advanced features like file uploads, request retries, and plugins, making it more versatile than d3-request.

README

d3-request

A convenient alternative to XMLHttpRequest. For example, to load a text file:

request("/path/to/file.txt", function(error, request) {
  if (error) return console.error(error.status);
  console.log(request.responseText); // Hello, world!
});

To load a CSV file:

csv("/path/to/file.csv", function(error, data) {
  if (error) return console.error(error.status);
  console.log(data); // [{"Hello": "world"}, …]
});

To post some query parameters:

request("/path/to/resource")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .post("a=2&b=3", callback);

This module includes support for parsing JSON, CSV and TSV out of the box.

Installing

If you use NPM, npm install d3-request. Otherwise, download the latest release.

API Reference

# request(url[, callback])

Returns a new asynchronous request for specified url. If no callback is specified, the request is not yet sent and can be further configured. If a callback is specified, it is equivalent to calling request.get immediately after construction:

request(url).get(callback);

Note: if you wish to specify a request header or a mime type, you must not specify a callback to the constructor. Use request.header or request.mimeType followed by request.get instead.

# request.header(name[, value])

If value is specified, sets the request header with the specified name to the specified value and returns this request instance. If value is null, removes the request header with the specified name instead. If value is not specified, returns the current value of the request header with the specified name. Header names are case-insensitive.

Request headers can only be modified before the request is sent. Therefore, you cannot pass a callback to the request constructor if you wish to specify a header; use request.get or similar instead. For example:

request(url).header("Accept-Language", "en-US").get(callback);

# request.mimeType([type])

If type is specified, sets the request mime type to the specified value and returns this request instance. If type is null, clears the current mime type (if any) instead. If type is not specified, returns the current mime type, which defaults to null. The mime type is used to both set the "Accept" request header and for overrideMimeType, where supported.

The request mime type can only be modified before the request is sent. Therefore, you cannot pass a callback to the request constructor if you wish to override the mime type; use request.get or similar instead. For example:

request(url).mimeType("text/csv").get(callback);

# request.responseType(type)

If type is specified, sets the response type attribute of the request and returns this request instance. Typical values are: "", "arraybuffer", "blob", "document", and "text". If type is not specified, returns the current response type, which defaults to "".

# request.response(value)

If value is specified, sets the response value function to the specified function and returns this request instance. If value is not specified, returns the current response value function, which defaults to the identity function.

The response value function is used to map the response XMLHttpRequest object to a useful data value. See the convenience methods json and text for examples.

# request.get([callback])

Equivalent to request.send with the GET method:

request.send("GET", callback);

# request.post([data][, callback])

Equivalent to request.send with the POST method:

request.send("POST", data, callback);

# request.send(method[, data][, callback])

Issues this request using the specified method (such as "GET" or "POST"), optionally posting the specified data in the request body, and returns this request instance. If a callback is specified, the callback will be invoked asynchronously when the request succeeds or fails. The callback is invoked with two arguments: the error, if any, and the response value. The response value is undefined if an error occurs. This is equivalent to:

request
    .on("error", function(xhr) { callback(xhr); })
    .on("load", function(xhr) { callback(null, xhr); })
    .send(method);

If no callback is specified, then "load" and "error" listeners should be registered via request.on.

# request.abort()

Aborts this request, if it is currently in-flight, and returns this request instance. See XMLHttpRequest’s abort.

# request.on(type[, listener])

If listener is specified, sets the event listener for the specified type and returns this request instance. If an event listener was already registered for the same type, the existing listener is removed before the new listener is added. If listener is null, removes the current event listener for the specified type (if any) instead. If listener is not specified, returns the currently-assigned listener for the specified type, if any.

The type must be one of the following:

• "beforesend" - to allow custom headers and the like to be set before the request is sent.
• "progress" - to monitor the progress of the request.
• "load" - when the request completes successfully.
• "error" - when the request completes unsuccessfully; this includes 4xx and 5xx response codes.

To register multiple listeners for the same type, the type may be followed by an optional name, such as "load.foo" and "load.bar". See d3-dispatch for details.

# csv(url[, row][, callback])

Creates a request for the CSV file at the specified url with the default mime type "text/csv". 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:

function row(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
  };
}

The row conversion function can be changed by calling request.row on the returned instance. For example, this:

csv(url, row, callback);

Is equivalent to this:

csv(url).row(row).get(callback);

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("text/csv")
    .response(function(xhr) { return csv.parse(xhr.responseText, row); })
    .get(callback);

# html(url[, callback])

Creates a request for the HTML file at the specified url with the default mime type "text/html". The HTML file is returned as a document fragment.

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("text/html")
    .response(function(xhr) { return document.createRange().createContextualFragment(xhr.responseText); })
    .get(callback);

# json(url[, callback])

Creates a request for the JSON file at the specified url with the default mime type "application/json".

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("application/json")
    .response(function(xhr) { return JSON.parse(xhr.responseText); })
    .get(callback);

# text(url[, callback])

Creates a request for the text file at the specified url with the default mime type "text/plain".

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("text/plain")
    .response(function(xhr) { return xhr.responseText; })
    .get(callback);

# tsv(url[, row][, callback])

Creates a request for the TSV file at the specified url with the default mime type "text/tab-separated-values". 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:

function row(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
  };
}

The row conversion function can be changed by calling request.row on the returned instance. For example, this:

tsv(url, row, callback);

Is equivalent to this:

tsv(url).row(row).get(callback);

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("text/tab-separated-values")
    .response(function(xhr) { return tsv.parse(xhr.responseText, row); })
    .get(callback);

# xml(url[, callback])

Creates a request for the XML file at the specified url with the default mime type "application/xml".

This convenience constructor is approximately equivalent to:

request(url)
    .mimeType("application/xml")
    .response(function(xhr) { return xhr.responseXML; })
    .get(callback);

Changes from D3 3.x:

• xhr has been renamed request.

• The request constructor no longer accepts an optional mime type argument. Use request.mimeType instead.

• Any progress event listener is passed the event directly as the first argument, rather than setting the d3.event global.