d3-request

This module provides a convenient alternative to XMLHttpRequest. For example, to load a text file:

d3.text("/path/to/file.txt", function(error, text) {
  if (error) throw error;
  console.log(text); // Hello, world!
});

To load and parse a CSV file:

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

To post some query parameters:

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

This module has built-in support for parsing JSON, CSV and TSV; in browsers, but not in Node, HTML and XML are also supported. You can parse additional formats by using request or text directly.

Installing

If you use NPM, npm install d3-request. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-collection.v1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v1.min.js"></script>
<script src="https://d3js.org/d3-dsv.v1.min.js"></script>
<script src="https://d3js.org/d3-request.v1.min.js"></script>
<script>
 
d3.csv("/path/to/file.csv", callback);
 
</script> 

Try d3-request in your browser.

API Reference

# d3.request(url[, callback]) <>

Returns a new request for specified url. If no callback is specified, the returned 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:

d3.request(url)
    .get(callback);

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. See d3.json, d3.csv, d3.tsv, d3.html and d3.xml for content-specific convenience constructors.

# 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:

d3.request(url)
    .header("Accept-Language", "en-US")
    .header("X-Requested-With", "XMLHttpRequest")
    .get(callback);

Note: this library does not set the X-Requested-With header to XMLHttpRequest by default. Some servers require this header to mitigate unwanted requests, but the presence of the header triggers CORS preflight checks; if necessary, set this header before sending the request.

# 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:

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

# request.user([value]) <>

If value is specified, sets the user name for authentication to the specified string and returns this request instance. If value is not specified, returns the current user name, which defaults to null.

# request.password([value]) <>

If value is specified, sets the password for authentication to the specified string and returns this request instance. If value is not specified, returns the current password, which defaults to null.

# request.timeout([timeout]) <>

If timeout is specified, sets the timeout attribute of the request to the specified number of milliseconds and returns this request instance. If timeout is not specified, returns the current response timeout, which defaults to 0.

# request.responseType([type]) <>

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

# request.response(value) <>

Sets the response value function to the specified function and returns this request instance. 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([data][, callback]) <>

Equivalent to request.send with the GET method:

request.send("GET", data, 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(error) { callback(error); })
    .on("load", function(xhr) { callback(null, xhr); })
    .send(method, data);

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.

# d3.csv(url[[, row], callback]) <>

Returns a new request for the CSV file at the specified url with the default mime type text/csv. If no callback is specified, this is equivalent to:

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

If a callback is specified, a GET request is sent, making it equivalent to:

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

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 returned request exposes an additional request.row method as an alternative to passing the row conversion function to d3.csv, allowing you to configure the request before sending it. For example, this:

d3.csv(url, row, callback);

Is equivalent to this:

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

# d3.html(url[, callback]) <>

Returns a new 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. If no callback is specified, this is equivalent to:

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

If a callback is specified, a GET request is sent, making it equivalent to:

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

HTML parsing requires a global document and relies on DOM Ranges, which are not supported by JSDOM as of version 8.3; thus, this method is supported in browsers but not in Node.

# d3.json(url[, callback]) <>

Returns a new request to get the JSON file at the specified url with the default mime type application/json. If no callback is specified, this is equivalent to:

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

If a callback is specified, a GET request is sent, making it equivalent to:

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

# d3.text(url[, callback]) <>

Returns a new request to get the text file at the specified url with the default mime type text/plain. If no callback is specified, this is equivalent to:

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

If a callback is specified, a GET request is sent, making it equivalent to:

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

# d3.tsv(url[[, row], callback]) <>

Returns a new request for a TSV file at the specified url with the default mime type text/tab-separated-values. If no callback is specified, this is equivalent to:

d3.request(url)
    .mimeType("text/tab-separated-values")
    .response(function(xhr) { return d3.tsvParse(xhr.responseText, row); });

If a callback is specified, a GET request is sent, making it equivalent to:

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

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 returned request exposes an additional request.row method as an alternative to passing the row conversion function to d3.tsv, allowing you to configure the request before sending it. For example, this:

d3.tsv(url, row, callback);

Is equivalent to this:

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

# d3.xml(url[, callback]) <>

Returns a new request to get the XML file at the specified url with the default mime type application/xml. If no callback is specified, this is equivalent to:

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

If a callback is specified, a GET request is sent, making it equivalent to:

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

XML parsing relies on xhr.responseXML which is not supported by node-XMLHttpRequest as of version 1.8; thus, this method is supported in browsers but not in Node.