URL API

The URL API is a component of the URL standard, which defines what constitutes a valid Uniform Resource Locator and the API that accesses and manipulates URLs. The URL standard also defines concepts such as domains, hosts, and IP addresses, and also attempts to describe in a standard way the legacy application/x-www-form-urlencoded MIME type used to submit web forms' contents as a set of key/value pairs.

URL concepts and usage

The majority of the URL standard is taken up by the definition of a URL and how it is structured and parsed. Also covered are definitions of various terms related to addressing of computers on a network, and the algorithms for parsing IP addresses and DOM addresses are specified. More interesting to most developers is the API itself.

Accessing URL components

Creating an URL object for a given URL parses the URL and provides quick access to its constituent parts through its properties.

let addr = new URL("/docs/Web/API/URL_API");
let host = addr.host;
let path = addr.pathname;

The snippet above creates a URL object for the article you're reading right now, then fetches the host and pathname properties. In this case, those strings are developer.mozilla.org and /docs/Web/API/URL_API, respectively.

Changing the URL

Most of the properties of URL are settable; you can write new values to them to alter the URL represented by the object. For example, to create a URL and set its username:

let myUsername = "someguy";
let addr = new URL("https://mysite.com/login");
addr.username = myUsername;

Setting the value of username not only sets that property's value, but it updates the overall URL. After executing the code snippet above, the value returned by addr.href is https://someguy@mysite.com/login. This is true for any of the writable properties.

Queries

The search property on a URL contains the query string portion of the URL. For example, if the URL is https://mysite.com/login?user=someguy&page=news, then the value of the search property is ?user=someguy&page=news. You can also look up the values of individual parameters with the URLSearchParams object's get() method:

let addr = new URL("https://mysite.com/login?user=someguy&page=news");
try {
  loginUser(addr.searchParams.get("user"));
  gotoPage(addr.searchParams.get("page"));
} catch(err) {
  showErrorMessage(err);
}

For example, in the above snippet, the username and target page are taken from the query and passed to appropriate functions that are used by the site's code to log in and route the user to their desired destination within the site.

Other functions within URLSearchParams let you change the value of keys, add and delete keys and their values, and even sort the list of parameters.

URL API interfaces

The URL API is a simple one, with only a couple of interfaces to its name:

Older versions of the specification included an interface called URLUtilsReadOnly, which has since been merged into the WorkerLocation interface.

Examples

If you want to process the parameters included in a URL, you could do it manually, but it's much easier to create a URL object to do it for you. The fillTableWithParameters() function below takes as input a HTMLTableElement object representing a <table>. Rows are added to the table, one for each key found in the parameters, with the first column containing the key's name, and the second column having the value.

Note the call to URLSearchParams.sort() to sort the parameter list before generating the table.

function fillTableWithParameters(tbl) {
  let url = new URL(document.location.href);
  url.searchParams.sort();
  let keys = url.searchParams.keys();

  for (let key of keys) {
    let val = url.searchParams.get(key);
    let row = document.createElement("tr");
    let cell = document.createElement("td");
    cell.innerText = key;
    row.appendChild(cell);
    cell = document.createElement("td");
    cell.innerText = val;
    row.appendChild(cell);
    tbl.appendChild(row);
  };
}

A working version of this example can be found on Glitch. Just add parameters to the URL when loading the page to see them in the table. For instance, try https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable.

Specifications

Specification Status Comment
URL Living Standard WHATWG specification

Browser compatibility

DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
URLChrome Full support 32
Full support 32
Full support 19
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge Full support 12Firefox Full support 19
Notes
Full support 19
Notes
Notes Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
Notes To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']);.
IE Full support 10Opera Full support 19
Full support 19
Full support 15
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Safari Full support 7
Full support 7
Full support 6
Prefixed
Prefixed Implemented with the vendor prefix: webkit
WebView Android Full support 4.4
Full support 4.4
Full support 4
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Chrome Android Full support 32
Full support 32
Full support 25
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Firefox Android Full support 19
Notes
Full support 19
Notes
Notes Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
Notes To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']);.
Opera Android Full support 19
Full support 19
Full support 14
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Safari iOS Full support 7
Full support 7
Full support 6
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Samsung Internet Android Full support 2.0
Full support 2.0
Full support 1.5
Prefixed
Prefixed Implemented with the vendor prefix: webkit
URL() constructorChrome Full support 19Edge Full support 12Firefox Full support 26IE No support NoOpera Full support 15Safari Full support 6WebView Android Full support ≤37Chrome Android Full support 25Firefox Android Full support 26Opera Android Full support 14Safari iOS Full support 6Samsung Internet Android Full support 1.5
createObjectURL
Experimental
Chrome Full support 19Edge Full support 12Firefox Full support 19
Notes
Full support 19
Notes
Notes createObjectURL() is no longer available within the context of a ServiceWorker.
IE Full support 10
Notes
Full support 10
Notes
Notes If the underlying object does not have a content type set, using this URL as the src of an img tag fails intermittently with error DOM7009.
Opera Full support 15Safari Full support 6WebView Android Full support YesChrome Android Full support 25Firefox Android Full support 19
Notes
Full support 19
Notes
Notes createObjectURL() is no longer available within the context of a ServiceWorker.
Opera Android Full support 14Safari iOS Full support 6Samsung Internet Android Full support 1.5
hashChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
hostChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
hostnameChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
hrefChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
originChrome Full support 32Edge Full support 12Firefox Full support 26
Full support 26
No support 26 — 49
Notes
Notes Results for URL using the blob scheme incorrectly returned null.
IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support ≤37Chrome Android Full support 32Firefox Android Full support 26
Full support 26
No support 26 — 49
Notes
Notes Results for URL using the blob scheme incorrectly returned null.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 6.0
passwordChrome Full support 32Edge Full support 12Firefox Full support 26IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support ≤37Chrome Android Full support 32Firefox Android Full support 26Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 6.0
pathnameChrome Full support YesEdge Full support 13Firefox Full support 53
Full support 53
No support 22 — 53
Notes
Notes pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 53
Full support 53
No support 22 — 53
Notes
Notes pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
portChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
protocolChrome Full support YesEdge Full support 13Firefox Full support 22IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 22Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
revokeObjectURL
Experimental
Chrome Full support 19Edge Full support 12Firefox Full support 19
Notes
Full support 19
Notes
Notes revokeObjectURL() is no longer available within the context of a ServiceWorker.
IE Full support 10Opera Full support 15Safari Full support 6WebView Android Full support ≤37Chrome Android Full support 25Firefox Android Full support 19
Notes
Full support 19
Notes
Notes revokeObjectURL() is no longer available within the context of a ServiceWorker.
Opera Android Full support 14Safari iOS Full support 6Samsung Internet Android Full support 1.5
searchChrome Full support YesEdge Full support 13Firefox Full support 53
Full support 53
No support 22 — 53
Notes
Notes pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesFirefox Android Full support 53
Full support 53
No support 22 — 53
Notes
Notes pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false, pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yes
searchParamsChrome Full support 51Edge Full support 17Firefox Full support 29IE No support NoOpera Full support 38Safari Full support 10WebView Android Full support 51Chrome Android Full support 51Firefox Android Full support 29Opera Android Full support 41Safari iOS Full support 10Samsung Internet Android Full support 5.0
toJSONChrome Full support 71Edge Full support 17Firefox Full support 54IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 54Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 10.0
toStringChrome Full support 19Edge Full support 17Firefox Full support 54IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support ≤37Chrome Android Full support 25Firefox Android Full support 54Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 6.0
usernameChrome Full support 32Edge Full support 12Firefox Full support 26IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support ≤37Chrome Android Full support 32Firefox Android Full support 26Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support 6.0

Legend

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
See implementation notes.
See implementation notes.
Requires a vendor prefix or different name for use.
Requires a vendor prefix or different name for use.

See also