{"id":15760447,"url":"https://github.com/d3/d3-request","last_synced_at":"2025-04-05T09:06:18.545Z","repository":{"id":33309267,"uuid":"36954008","full_name":"d3/d3-request","owner":"d3","description":"A convenient alternative to XMLHttpRequest.","archived":false,"fork":false,"pushed_at":"2018-02-01T11:03:54.000Z","size":95,"stargazers_count":108,"open_issues_count":5,"forks_count":54,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-29T08:05:39.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-06-05T20:30:46.000Z","updated_at":"2025-03-01T06:12:27.000Z","dependencies_parsed_at":"2022-08-19T08:11:19.824Z","dependency_job_id":null,"html_url":"https://github.com/d3/d3-request","commit_stats":null,"previous_names":["d3/d3-xhr"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3%2Fd3-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3%2Fd3-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3%2Fd3-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d3%2Fd3-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d3","download_url":"https://codeload.github.com/d3/d3-request/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312077,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-04T10:58:02.378Z","updated_at":"2025-04-05T09:06:18.500Z","avatar_url":"https://github.com/d3.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# d3-request\n\n**This module is deprecated as of D3 5.0; please use [d3-fetch](https://github.com/d3/d3-fetch) instead.**\n\nThis module provides a convenient alternative to XMLHttpRequest. For example, to load a text file:\n\n```js\nd3.text(\"/path/to/file.txt\", function(error, text) {\n  if (error) throw error;\n  console.log(text); // Hello, world!\n});\n```\n\nTo load and parse a CSV file:\n\n```js\nd3.csv(\"/path/to/file.csv\", function(error, data) {\n  if (error) throw error;\n  console.log(data); // [{\"Hello\": \"world\"}, …]\n});\n```\n\nTo post some query parameters:\n\n```js\nd3.request(\"/path/to/resource\")\n    .header(\"X-Requested-With\", \"XMLHttpRequest\")\n    .header(\"Content-Type\", \"application/x-www-form-urlencoded\")\n    .post(\"a=2\u0026b=3\", callback);\n```\n\nThis module has built-in support for parsing [JSON](#json), [CSV](#csv) and [TSV](#tsv); in browsers, but not in Node, [HTML](#html) and [XML](#xml) are also supported. You can parse additional formats by using [request](#request) or [text](#text) directly.\n\n## Installing\n\nIf you use NPM, `npm install d3-request`. Otherwise, download the [latest release](https://github.com/d3/d3-request/releases/latest). You can also load directly from [d3js.org](https://d3js.org), either as a [standalone library](https://d3js.org/d3-request.v1.min.js) or as part of [D3 4.0](https://github.com/d3/d3). AMD, CommonJS, and vanilla environments are supported. In vanilla, a `d3` global is exported:\n\n```html\n\u003cscript src=\"https://d3js.org/d3-collection.v1.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://d3js.org/d3-dispatch.v1.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://d3js.org/d3-dsv.v1.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://d3js.org/d3-request.v1.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\nd3.csv(\"/path/to/file.csv\", callback);\n\n\u003c/script\u003e\n```\n\n## API Reference\n\n\u003ca name=\"request\" href=\"#request\"\u003e#\u003c/a\u003e d3.\u003cb\u003erequest\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L4 \"Source\")\n\nReturns a new *request* for specified *url*. If no *callback* is specified, the returned *request* is not yet [sent](#request_send) and can be further configured. If a *callback* is specified, it is equivalent to calling [*request*.get](#request_get) immediately after construction:\n\n```js\nd3.request(url)\n    .get(callback);\n```\n\nIf you wish to specify a request header or a mime type, you must *not* specify a callback to the constructor. Use [*request*.header](#request_header) or [*request*.mimeType](#request_mimeType) followed by [*request*.get](#request_get) instead. See [d3.json](#json), [d3.csv](#csv), [d3.tsv](#tsv), [d3.html](#html) and [d3.xml](#xml) for content-specific convenience constructors.\n\n\u003ca name=\"request_header\" href=\"#request_header\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eheader\u003c/b\u003e(\u003ci\u003ename\u003c/i\u003e[, \u003ci\u003evalue\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L51 \"Source\")\n\nIf *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.\n\nRequest headers can only be modified before the request is [sent](#request_send). Therefore, you cannot pass a callback to the [request constructor](#request) if you wish to specify a header; use [*request*.get](#request_get) or similar instead. For example:\n\n```js\nd3.request(url)\n    .header(\"Accept-Language\", \"en-US\")\n    .header(\"X-Requested-With\", \"XMLHttpRequest\")\n    .get(callback);\n```\n\nNote: 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.\n\n\u003ca name=\"request_mimeType\" href=\"#request_mimeType\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003emimeType\u003c/b\u003e([\u003ci\u003etype\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L60 \"Source\")\n\nIf *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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) and for [overrideMimeType](http://www.w3.org/TR/XMLHttpRequest/#the-overridemimetype%28%29-method), where supported.\n\nThe request mime type can only be modified before the request is [sent](#request_send). Therefore, you cannot pass a callback to the [request constructor](#request) if you wish to override the mime type; use [*request*.get](#request_get) or similar instead. For example:\n\n```js\nd3.request(url)\n    .mimeType(\"text/csv\")\n    .get(callback);\n```\n\n\u003ca name=\"request_user\" href=\"#request_user\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003euser\u003c/b\u003e([\u003ci\u003evalue\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L80 \"Source\")\n\nIf *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.\n\n\u003ca name=\"request_password\" href=\"#request_password\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003epassword\u003c/b\u003e([\u003ci\u003evalue\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L84 \"Source\")\n\nIf *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.\n\n\u003ca name=\"request_timeout\" href=\"#request_timeout\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003etimeout\u003c/b\u003e([\u003ci\u003etimeout\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L74 \"Source\")\n\nIf *timeout* is specified, sets the [timeout](http://www.w3.org/TR/XMLHttpRequest/#the-timeout-attribute) 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.\n\n\u003ca name=\"request_responseType\" href=\"#request_responseType\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eresponseType\u003c/b\u003e([\u003ci\u003etype\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L68 \"Source\")\n\nIf *type* is specified, sets the [response type](http://www.w3.org/TR/XMLHttpRequest/#the-responsetype-attribute) 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 `​`.\n\n\u003ca name=\"request_response\" href=\"#request_response\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eresponse\u003c/b\u003e(\u003ci\u003evalue\u003c/i\u003e) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L90 \"Source\")\n\nSets 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](#json) and [text](#text) for examples.\n\n\u003ca name=\"request_get\" href=\"#request_get\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eget\u003c/b\u003e([\u003ci\u003edata\u003c/i\u003e][, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L96 \"Source\")\n\nEquivalent to [*request*.send](#request_send) with the GET method:\n\n```js\nrequest.send(\"GET\", data, callback);\n```\n\n\u003ca name=\"request_post\" href=\"#request_post\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003epost\u003c/b\u003e([\u003ci\u003edata\u003c/i\u003e][, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L101 \"Source\")\n\nEquivalent to [*request*.send](#request_send) with the POST method:\n\n```js\nrequest.send(\"POST\", data, callback);\n```\n\n\u003ca name=\"request_send\" href=\"#request_send\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003esend\u003c/b\u003e(\u003ci\u003emethod\u003c/i\u003e[, \u003ci\u003edata\u003c/i\u003e][, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L106 \"Source\")\n\nIssues 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](#request_response). The response value is undefined if an error occurs. This is equivalent to:\n\n```js\nrequest\n    .on(\"error\", function(error) { callback(error); })\n    .on(\"load\", function(xhr) { callback(null, xhr); })\n    .send(method, data);\n```\n\nIf no *callback* is specified, then \"load\" and \"error\" listeners should be registered via [*request*.on](#request_on).\n\n\u003ca name=\"request_abort\" href=\"#request_abort\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eabort\u003c/b\u003e() [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L121 \"Source\")\n\nAborts this request, if it is currently in-flight, and returns this request instance. See [XMLHttpRequest’s abort](http://www.w3.org/TR/XMLHttpRequest/#the-abort%28%29-method).\n\n\u003ca name=\"request_on\" href=\"#request_on\"\u003e#\u003c/a\u003e \u003ci\u003erequest\u003c/i\u003e.\u003cb\u003eon\u003c/b\u003e(\u003ci\u003etype\u003c/i\u003e[, \u003ci\u003elistener\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/request.js#L126 \"Source\")\n\nIf *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.\n\nThe type must be one of the following:\n\n* `beforesend` - to allow custom headers and the like to be set before the request is [sent](#request_send).\n* `progress` - to monitor the [progress of the request](http://www.w3.org/TR/progress-events/).\n* `load` - when the request completes successfully.\n* `error` - when the request completes unsuccessfully; this includes 4xx and 5xx response codes.\n\nTo 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](https://github.com/d3/d3-dispatch) for details.\n\n\u003ca name=\"csv\" href=\"#csv\"\u003e#\u003c/a\u003e d3.\u003cb\u003ecsv\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[[, \u003ci\u003erow\u003c/i\u003e], \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/csv.js \"Source\")\n\nReturns a new [*request*](#request) for the [CSV](https://github.com/d3/d3-dsv#csvParse) file at the specified *url* with the default mime type `text/csv`. If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/csv\")\n    .response(function(xhr) { return d3.csvParse(xhr.responseText, row); });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/csv\")\n    .response(function(xhr) { return d3.csvParse(xhr.responseText, row); })\n    .get(callback);\n```\n\nAn optional *row* conversion function may be specified to map and filter row objects to a more-specific representation; see [*dsv*.parse](https://github.com/d3/d3-dsv#dsv_parse) for details. For example:\n\n```js\nfunction row(d) {\n  return {\n    year: new Date(+d.Year, 0, 1), // convert \"Year\" column to Date\n    make: d.Make,\n    model: d.Model,\n    length: +d.Length // convert \"Length\" column to number\n  };\n}\n```\n\nThe 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:\n\n```js\nd3.csv(url, row, callback);\n```\n\nIs equivalent to this:\n\n```js\nd3.csv(url)\n    .row(row)\n    .get(callback);\n```\n\n\u003ca name=\"html\" href=\"#html\"\u003e#\u003c/a\u003e d3.\u003cb\u003ehtml\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/html.js \"Source\")\n\nReturns a new [*request*](#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](https://developer.mozilla.org/en-US/docs/DOM/range.createContextualFragment). If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/html\")\n    .response(function(xhr) { return document.createRange().createContextualFragment(xhr.responseText); });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/html\")\n    .response(function(xhr) { return document.createRange().createContextualFragment(xhr.responseText); })\n    .get(callback);\n```\n\nHTML parsing requires a global document and relies on [DOM Ranges](https://dom.spec.whatwg.org/#ranges), which are [not supported by JSDOM](https://github.com/tmpvar/jsdom/issues/317) as of version 8.3; thus, this method is supported in browsers but not in Node.\n\n\u003ca name=\"json\" href=\"#json\"\u003e#\u003c/a\u003e d3.\u003cb\u003ejson\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/json.js \"Source\")\n\nReturns a new [*request*](#request) to [get](#request_get) the [JSON](http://json.org) file at the specified *url* with the default mime type `application/json`. If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"application/json\")\n    .response(function(xhr) { return JSON.parse(xhr.responseText); });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"application/json\")\n    .response(function(xhr) { return JSON.parse(xhr.responseText); })\n    .get(callback);\n```\n\n\u003ca name=\"text\" href=\"#text\"\u003e#\u003c/a\u003e d3.\u003cb\u003etext\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/text.js \"Source\")\n\nReturns a new [*request*](#request) to [get](#request_get) the text file at the specified *url* with the default mime type `text/plain`. If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/plain\")\n    .response(function(xhr) { return xhr.responseText; });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/plain\")\n    .response(function(xhr) { return xhr.responseText; })\n    .get(callback);\n```\n\n\u003ca name=\"tsv\" href=\"#tsv\"\u003e#\u003c/a\u003e d3.\u003cb\u003etsv\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[[, \u003ci\u003erow\u003c/i\u003e], \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/tsv.js \"Source\")\n\nReturns a new [*request*](#request) for a [TSV](https://github.com/d3/d3-dsv#tsvParse) file at the specified *url* with the default mime type `text/tab-separated-values`. If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/tab-separated-values\")\n    .response(function(xhr) { return d3.tsvParse(xhr.responseText, row); });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"text/tab-separated-values\")\n    .response(function(xhr) { return d3.tsvParse(xhr.responseText, row); })\n    .get(callback);\n```\n\nAn optional *row* conversion function may be specified to map and filter row objects to a more-specific representation; see [*dsv*.parse](https://github.com/d3/d3-dsv#dsv_parse) for details. For example:\n\n```js\nfunction row(d) {\n  return {\n    year: new Date(+d.Year, 0, 1), // convert \"Year\" column to Date\n    make: d.Make,\n    model: d.Model,\n    length: +d.Length // convert \"Length\" column to number\n  };\n}\n```\n\nThe 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:\n\n```js\nd3.tsv(url, row, callback);\n```\n\nIs equivalent to this:\n\n```js\nd3.tsv(url)\n    .row(row)\n    .get(callback);\n```\n\n\u003ca name=\"xml\" href=\"#xml\"\u003e#\u003c/a\u003e d3.\u003cb\u003exml\u003c/b\u003e(\u003ci\u003eurl\u003c/i\u003e[, \u003ci\u003ecallback\u003c/i\u003e]) [\u003c\u003e](https://github.com/d3/d3-request/blob/master/src/xml.js \"Source\")\n\nReturns a new [*request*](#request) to [get](#request_get) the XML file at the specified *url* with the default mime type `application/xml`. If no *callback* is specified, this is equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"application/xml\")\n    .response(function(xhr) { return xhr.responseXML; });\n```\n\nIf a *callback* is specified, a [GET](#request_get) request is sent, making it equivalent to:\n\n```js\nd3.request(url)\n    .mimeType(\"application/xml\")\n    .response(function(xhr) { return xhr.responseXML; })\n    .get(callback);\n```\n\nXML parsing relies on [*xhr*.responseXML](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseXML) which is not supported by [node-XMLHttpRequest](https://github.com/driverdan/node-XMLHttpRequest/issues/8) as of version 1.8; thus, this method is supported in browsers but not in Node.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3%2Fd3-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd3%2Fd3-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd3%2Fd3-request/lists"}