GM.xmlHttpRequest

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

Syntax

GM_xmlhttpRequest( details )

Value: Function

Returns: undefined, response Object

Compatibility: Greasemonkey 0.2.5+

details Object

Properties	Event Handler Callbacks
method	onload
url	onreadystatechange
headers	onerror
overrideMimeType
data
binary

• 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.greasespot.net/";

• Must be an absolute URL.

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+

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 */ }

• ^[1]
• 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

Usage: details.binary = true;

Compatibility: Greasemonkey 0.8.3+

• Optional. Default false. If true, the underling xmlHttpRequest will have .sendAsBinary() instead of .send() called.

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

response Object

Properties
status	readyState	responseText	finalUrl
statusText		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+

Usage: if (response.finalUrl) { /* some code */ }

Examples

Core

GET request

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) {
    // Inject responseXML into existing Object if not present
    if (!response.responseXML)
      response.responseXML = new DOMParser().parseFromString(response.responseText, "text/xml");

    GM_log([
      response.status,
      response.statusText,
      response.readyState,
      response.responseHeaders,
      response.responseText,
      response.finalUrl,
      response.responseXML
    ].join("\n"));
  }
});

}}

POST request

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

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") > -1)
      location.href = "http://www.example.net/dashboard";
  }
});

}}

HEAD request

Sometimes responseText may be unnecessary, in which case a "HEAD" request is more advisable.

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

}}

Notes

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

• http://www.mozdev.org/pipermail/greasemonkey/2006-June/008785.html
• http://www.mozdev.org/pipermail/greasemonkey/2006-April/008064.html

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

^[2]Some 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.

• http://groups.google.com/group/greasemonkey-dev/browse_thread/thread/77c94cc17c6b2669
• http://userscripts.org/forums/1/topics/1302