Repository files navigation

This module is deprecated as of D3 5.0; please used3-fetch instead.

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)throwerror;console.log(text);// Hello, world!});

To load and parse a CSV file:

d3.csv("/path/to/file.csv",function(error,data){if(error)throwerror;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 parsingJSON,CSV andTSV; in browsers, but not in Node,HTML andXML are also supported. You can parse additional formats by usingrequest ortext directly.

If you use NPM,npm install d3-request. Otherwise, download thelatest release. You can also load directly fromd3js.org, either as astandalone library or as part ofD3 4.0. AMD, CommonJS, and vanilla environments are supported. In vanilla, ad3 global is exported:

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

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

Returns a newrequest for specifiedurl. If nocallback is specified, the returnedrequest is not yetsent and can be further configured. If acallback is specified, it is equivalent to callingrequest.get immediately after construction:

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

If you wish to specify a request header or a mime type, you mustnot specify a callback to the constructor. Userequest.header orrequest.mimeType followed byrequest.get instead. Seed3.json,d3.csv,d3.tsv,d3.html andd3.xml for content-specific convenience constructors.

#request.header(name[,value])<>

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

Request headers can only be modified before the request issent. Therefore, you cannot pass a callback to therequest constructor if you wish to specify a header; userequest.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 toXMLHttpRequest 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])<>

Iftype is specified, sets the request mime type to the specified value and returns this request instance. Iftype is null, clears the current mime type (if any) instead. Iftype 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 foroverrideMimeType, where supported.

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

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

#request.user([value])<>

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

#request.password([value])<>

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

#request.timeout([timeout])<>

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

#request.responseType([type])<>

Iftype is specified, sets theresponse type attribute of the request and returns this request instance. Typical values are:​ (the empty string),arraybuffer,blob,document, andtext. Iftype 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 methodsjson andtext for examples.

#request.get([data][,callback])<>

Equivalent torequest.send with the GET method:

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

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

Equivalent torequest.send with the POST method:

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

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

Issues this request using the specifiedmethod (such asGET orPOST), optionally posting the specifieddata in the request body, and returns this request instance. If acallback 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 theresponse 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 nocallback is specified, then "load" and "error" listeners should be registered viarequest.on.

#request.abort()<>

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

#request.on(type[,listener])<>

Iflistener is specified, sets the eventlistener for the specifiedtype 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. Iflistener is null, removes the current eventlistener for the specifiedtype (if any) instead. Iflistener 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 issent.
• progress - to monitor theprogress 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 sametype, the type may be followed by an optional name, such asload.foo andload.bar. Seed3-dispatch for details.

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

Returns a newrequest for theCSV file at the specifiedurl with the default mime typetext/csv. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

An optionalrow conversion function may be specified to map and filter row objects to a more-specific representation; seedsv.parse for details. For example:

functionrow(d){return{year:newDate(+d.Year,0,1),// convert "Year" column to Datemake:d.Make,model:d.Model,length:+d.Length// convert "Length" column to number};}

The returnedrequest exposes an additionalrequest.row method as an alternative to passing therow 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 newrequest for the HTML file at the specifiedurl with the default mime typetext/html. The HTML file is returned as adocument fragment. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

HTML parsing requires a global document and relies onDOM Ranges, which arenot 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 newrequest toget theJSON file at the specifiedurl with the default mime typeapplication/json. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

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

Returns a newrequest toget the text file at the specifiedurl with the default mime typetext/plain. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

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

Returns a newrequest for aTSV file at the specifiedurl with the default mime typetext/tab-separated-values. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

An optionalrow conversion function may be specified to map and filter row objects to a more-specific representation; seedsv.parse for details. For example:

functionrow(d){return{year:newDate(+d.Year,0,1),// convert "Year" column to Datemake:d.Make,model:d.Model,length:+d.Length// convert "Length" column to number};}

The returnedrequest exposes an additionalrequest.row method as an alternative to passing therow 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 newrequest toget the XML file at the specifiedurl with the default mime typeapplication/xml. If nocallback is specified, this is equivalent to:

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

If acallback is specified, aGET request is sent, making it equivalent to:

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

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