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.

Issuing 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.

This method is typically 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)

Issues an HTTP GET request for the text file at the specified url. An optional mime type may be specified as the second argument, such as "text/plain". The request is processed asynchronously, such that this method returns immediately after opening the request. When the text is available, the specified callback will be invoked, being passed the text string, per the responseText attribute of the request. If an error occurs, the callback function will instead be invoked with null.

# d3.json(url, callback)

Issues an HTTP GET request for the JSON file at the specified url. The mime type "application/json" will be used. The request is processed asynchronously, such that this method returns immediately after opening the request. When the text is available, the specified callback will be invoked, being passed the JSON result (typically, an object or an array, depending on the contents of the file), parsed from the responseText attribute of the request. If an error occurs, the callback function will instead be invoked with null.

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

Issues an HTTP GET request for the XML file at the specified url. An optional mime type may be specified as the second argument, such as "application/xml". The request is processed asynchronously, such that this method returns immediately after opening the request. When the XML content is available, the specified callback will be invoked, being passed the root (document) element of the loaded XML content, per the responseXML attribute of the request. If an error occurs, the callback function will instead be invoked with null.

# d3.html(url, callback)

Issues an HTTP GET request for the HTML file at the specified url. The mime type "text/html" will be used. The request is processed asynchronously, such that this method returns immediately after opening the request. When the HTML content is available, the specified callback will be invoked, being passed the root (document) element of the loaded HTML content. This is generated as a document fragment from the responseText attribute of the request. If an error occurs, the callback function will instead be invoked with null.

# d3.csv(url, callback)

See CSV.