Greasemonkey Wiki

Brought to you by: mmartz

GM_xmlhttpRequest

There is a newer version of this page. You can find it here.

Description

This API method provides access to the chrome-privileged XMLHttpRequest object. This means that it is possible to issue requests to domains other than that of the current page.

Additional reference may be found at:

http://www.w3.org/TR/XMLHttpRequest

{{toFirstLast}} | Examples | See Also | Notes

Syntax

GM_xmlhttpRequest( details )

Value: Function 
Returns:

 undefined with [Greasemonkey 1.8.0-](Version_history#1.9.0) 
 Object with [Greasemonkey 1.9.0+](Version_history#1.9.0) 
Compatibility: [Greasemonkey 0.2.5+](Version_history#0.2.5) 
Access: [@grant](Metadata_Block#.40grant_)

details Object

Properties Event Handler Callbacks

[method](#method_)

[onload](#onload)

[url](#url_)

[onreadystatechange](#onreadystatechange)

[headers](#headers_)

[onerror](#onerror)

[overrideMimeType](#overrideMimeType_)

[ontimeout](#ontimeout)

[data](#data_)

[onprogress](#onprogress)

[binary](#binary_)

[onabort](#onabort)

[user](#user_)

[password](#password_)

[upload](#upload_)

[synchronous](#synchronous_)

[timeout](#timeout_)

All properties and event handler callbacks are optional except method and url.

Properties

method

Value: String 
Usage:

_details_.**method** = "GET";

url

Value: String 
Usage:

_details_.**url** = "http://www.example.com/";

The URL may be relative but it is strongly recommended to make it an absolute URL to avoid incorrect domain requests depending on the complexity of a user script.

headers

Value: Object 
Usage:

_details_.**headers** = {"User-Agent":"Mozilla/5.0"};

The
```
headers
```

property is an object which is typically used to override the default browser generated headers, also known as atoms. It should contain the atom-value pairs of the headers to send.2

overrideMimeType

Value: String 
Compatibility: [Greasemonkey 0.6.8+](Version_history#0.6.8) 
Usage:

_details_.**overrideMimeType** = "text/html; charset=ISO-8859-1";

While each character set name may have multiple aliases defined, there may be a preferred name which can be found at IANA

data

Value: String 
Usage:

_details_.**data** = null; _/* some code */_ if (_details_.**data**) { _/* some code */_ }

Note that if the
```
data
```

field contains form-encoded data, you must also set the header

    'Content-Type': 'application/x-www-form-urlencoded'

in the

    headers

field.

binary

Value: Boolean 
Compatibility: [Greasemonkey 0.8.3+](Version_history#0.8.20091129.3) 
Usage:

_details_.**binary** = true;

Sends data as type binary in Firefox 3.0.x or above.

user

Value: String 
Compatibility: [Greasemonkey 0.9.0+](Version_history#0.9.0) 
Usage:

_details_.**user** = "johndoe";

password

Value: String 
Compatibility: [Greasemonkey 0.9.0+](Version_history#0.9.0) 
Usage:

_details_.**password** = "password";

upload

Value: Object 
Compatibility: [Greasemonkey 0.9.9+](Version_history#0.9.9)

synchronous

Value: Boolean 
Compatibility: [Greasemonkey 0.9.9+](Version_history#0.9.9)

timeout

Value: Number 
Compatibility: [Greasemonkey 1.0.0+](Version_history#1.0.0)

Event Handler Callbacks

onload

Usage:

_details_.**onload** = function (_response_) { _/* some code */_ };

Returns: undefined, response Object

onreadystatechange

Usage:

_details_.**onreadystatechange** = function (_response_) { _/* some code */_ };

Returns: undefined, response Object

onerror

Usage:

_details_.**onerror** = function (_response_) { _/* some code */_ };

Returns: undefined, response Object

ontimeout

Usage:

_details_.**ontimeout** = function (_response_) { _/* some code */_ };

Compatibility: [Greasemonkey 0.9.9+](Version_history#0.9.9)*

onprogress

Usage:

_details_.**onprogress** = function (_response_) { _/* some code */_ };

Compatibility: [Greasemonkey 0.9.9+](Version_history#0.9.9)*

onabort

Usage:

_details_.**onabort** = function (_response_) { _/* some code */_ };

Compatibility: [Greasemonkey 0.9.9+](Version_history#0.9.9)*

response Object

Properties

[status](#status_)

[readyState](#readyState_)

[responseText](#responseText_)

[finalUrl](#finalUrl_)

[statusText](#statusText_)

[responseHeaders](#responseHeaders_)

Note: there is no
```
responseXML
```

property, contrary to what people used to XMLHttpRequest might expect. This is due to security restrictions imposed on the XMLDocument created in the privileged GM core context. One can easily create its own XMLDocument out of

    responseText

using a DOMParser (see examples below).

Properties

status

Value: Number 
Usage:

if (_response_.**status** == 200) { _/* some code */_ }

statusText

Value: String 
Usage:

if (_response_.**statusText** == "OK") { _/* some code */_ }

readyState

Value: Number 
Usage:

if (_response_.**readyState** == 4) { _/* some code */_ }

responseText

Value: String 
Usage:

alert(_response_.**responseText**);

responseHeaders

Value: String 
Usage:

if (_response_.**responseHeaders**) { _/* some code */_ }

The
```
responseHeaders
```

is the string representation of response headers returned by

    XMLHTTPRequest.getAllResponseHeaders()

finalUrl

Value: String 
Compatibility: [Greasemonkey 0.8.0+](Version_history#0.8.20080609.0) 
Usage:

if (_response_.**finalUrl**) { _/* some code */_ }

Examples

{{toFirstLast}} | GET request | POST request | HEAD request

Core

GET request

{{Core samp |1=

GM_xmlhttpRequest({
  method: "GET",
  url: "http://www.example.net/",
  headers: {
    "User-Agent": "Mozilla/5.0",            // If not specified, navigator.userAgent will be used.
    "Accept": "text/xml"                    // If not specified, browser defaults will be used.
  },
  onload: function(response) {
    GM_log([
      response.status,
      response.statusText,
      response.readyState,
      response.responseHeaders,
      response.responseText,
      response.finalUrl
    ].join("\n"));
  }
});

}}

POST request

When making a POST request, some sites require the Content-Type header to be included as such:

{{Core samp |1=

GM_xmlhttpRequest({
  method: "POST",
  url: "http://www.example.net/login",
  data: "username=johndoe&password=xyz123",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  onload: function(response) {
    if (response.responseText.indexOf("Logged in as") &gt; -1)
      location.href = "http://www.example.net/dashboard";
  }
});

}}

HEAD request

Sometimes

responseText

may be unnecessary, in which case a "HEAD" request is more advisable. {{Core samp |1=

GM_xmlhttpRequest({
  url: "http://www.example.com",
  method: "HEAD",
  onload: function(response) {
    GM_log(response.responseHeaders);
  }
});

}}

Notes

1Some users have reported problems with international character sets. See these [Mailing_list] threads

Resolved: Greasemonkey exposed the overrideMimeType method to allow changing of the desired charset.

2Some header atoms may not actually work through GM_xmlhttpRequest. The Referer atom is one that is known to be recognized but appears to be content filtered by the browser. This may be due to security restrictions to keep user scripts from doing unsafe things.