Requests

Wiki ▸ API Reference ▸ Core ▸ Requests

You can’t visualize data if you can’t access it! Fortunately, there are many ways to get data into the browser. For small datasets, you might hardcode the data in your script, or embed data in the DOM using data attributes. For larger datasets, you could load an external script that defines your data as a global variable. (JSONP is a common example of this.) But, the most versatile way of loading data into the browser is using an XMLHttpRequest, or XHR. This allows data to be loaded asynchronously (so the rest of the page can display while data is loading), and is safer than JSONP. D3’s xhr module simplifies loading and parsing data.

When loading data asynchronously, code that depends on the loaded data should generally exist within the callback function. For example, see the calendar visualization on the D3 website. Code that doesn't depend on data can run immediately when the page loads. Also, you may find it convenient to save loaded data to the global namespace, so that you can access it after the initial render, such as during a transition. You can do this using closures, or simply assign the loaded data to a global:

var data; // a global

d3.json("path/to/file.json", function(json) {
  data = json;
  visualizeit();
});

By default, most browsers do not allow cross-domain requests. To enable cross-domain requests, have the server set the header Access-Control-Allow-Origin: *. For more details, see the W3C recommendation on Cross-Origin Resource Sharing.

Requests

# d3.xhr(url[, mime], callback)

Issues an HTTP GET request for the specified url. An optional mime type may be specified as the second argument, such as "application/json". The request is processed asynchronously, such that this method returns immediately after opening the request. When the data is available, the specified callback will be invoked, being passed the XMLHttpRequest object. If an error occurs, the callback function will instead be invoked with null.

Convenience Methods

Often, d3.xhr is not used directly. Instead, one of the type-specific methods is used instead, such as: text for plain text, json for JSON, xml for XML, html for HTML, and csv for comma-separated values.

# d3.text(url[, mime][, callback])

Creates a request for the text file at the specified url. An optional mime type may be specified as the second argument, such as "text/plain". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the response text. The response text is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.

# d3.json(url[, callback])

Creates a request for the JSON file at the specified url with the mime type "application/json". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the parsed JSON. The parsed JSON is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.

# d3.xml(url[, mime][, callback])

Creates a request for the XML file at the specified url. An optional mime type may be specified as the second argument, such as "application/xml". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the parsed XML as a document. The parsed XML is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.

# d3.html(url[, callback])

Creates a request for the HTML file at the specified url with the mime type "text/html". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the parsed HTML as a document fragment. The parsed HTML is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.

# d3.csv(url[, callback])

Creates a request for the CSV file at the specified url with the mime type "text/csv". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the array of parsed rows per RFC 4180. The rows array is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.

# d3.tsv(url[, callback])

Creates a request for the TSV file at the specified url with the mime type "text/tab-separated-values". If a callback is specified, the request is immediately issued as a GET request, and the callback will be invoked asynchronously when the file is loaded or the request fails; the callback is invoked with two arguments: the error, if any, and the array of parsed rows per RFC 4180. The rows array is undefined if an error occurs. If no callback is specified, the returned request can be issued using xhr.get or similar, and handled using xhr.on.