Web/API/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("https://developer.mozilla.org/en-US/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 /en-US/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://[email protected]/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

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`URL`	Chrome Full support 32 Full support 32 Full support 19 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Edge Full support 12	Firefox 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 10	Opera 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()` constructor	Chrome Full support 19	Edge Full support 12	Firefox Full support 26	IE No support No	Opera Full support 15	Safari Partial support 6 Notes' Partial support 6 Notes' Notes' In Safari 14 and earlier, calling the `URL` constructor with a base URL whose value is `undefined` causes Safari to throw a `TypeError`; see WebKit bug 216841.	WebView Android Full support ≤37	Chrome Android Full support 25	Firefox Android Full support 26	Opera Android Full support 14	Safari iOS Partial support 6 Notes' Partial support 6 Notes' Notes' In Safari 14 and earlier, calling the `URL` constructor with a base URL whose value is `undefined` causes Safari to throw a `TypeError`; see WebKit bug 216841.	Samsung Internet Android Full support 1.5
`createObjectURL` Experimental'	Chrome Full support 19	Edge Full support 12	Firefox 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 15	Safari Full support 6	WebView Android Full support Yes	Chrome Android Full support 25	Firefox 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 14	Safari iOS Full support 6	Samsung Internet Android Full support 1.5
`hash`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support Yes	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`host`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support Yes	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`hostname`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`href`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`origin`	Chrome Full support 32	Edge Full support 12	Firefox 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 No	Opera Full support Yes	Safari Full support 10	WebView Android Full support ≤37	Chrome Android Full support 32	Firefox 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 Yes	Safari iOS Full support Yes	Samsung Internet Android Full support 6.0
`password`	Chrome Full support 32	Edge Full support 12	Firefox Full support 26	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support ≤37	Chrome Android Full support 32	Firefox Android Full support 26	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support 6.0
`pathname`	Chrome Full support Yes	Edge Full support 13	Firefox 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 No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox 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 Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`port`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`protocol`	Chrome Full support Yes	Edge Full support 13	Firefox Full support 22	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox Android Full support 22	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`revokeObjectURL` Experimental'	Chrome Full support 19	Edge Full support 12	Firefox Full support 19 Notes' Full support 19 Notes' Notes' `revokeObjectURL()` is no longer available within the context of a `ServiceWorker`.	IE Full support 10	Opera Full support 15	Safari Full support 6	WebView Android Full support ≤37	Chrome Android Full support 25	Firefox 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 14	Safari iOS Full support 6	Samsung Internet Android Full support 1.5
`search`	Chrome Full support Yes	Edge Full support 13	Firefox 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 No	Opera Full support Yes	Safari Full support 10	WebView Android Full support Yes	Chrome Android Full support Yes	Firefox 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 Yes	Safari iOS Full support Yes	Samsung Internet Android Full support Yes
`searchParams`	Chrome Full support 51	Edge Full support 17	Firefox Full support 29	IE No support No	Opera Full support 38	Safari Full support 10	WebView Android Full support 51	Chrome Android Full support 51	Firefox Android Full support 29	Opera Android Full support 41	Safari iOS Full support 10	Samsung Internet Android Full support 5.0
`toJSON`	Chrome Full support 71	Edge Full support 17	Firefox Full support 54	IE No support No	Opera Full support Yes	Safari Full support Yes	WebView Android Full support 71	Chrome Android Full support 71	Firefox Android Full support 54	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support 10.0
`toString`	Chrome Full support 19	Edge Full support 17	Firefox Full support 54	IE No support No	Opera Full support Yes	Safari Full support Yes	WebView Android Full support ≤37	Chrome Android Full support 25	Firefox Android Full support 54	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support 6.0
`username`	Chrome Full support 32	Edge Full support 12	Firefox Full support 26	IE No support No	Opera Full support Yes	Safari Full support 10	WebView Android Full support ≤37	Chrome Android Full support 32	Firefox Android Full support 26	Opera Android Full support Yes	Safari iOS Full support Yes	Samsung Internet Android Full support 6.0

Legend

Full support: Full support
Partial support: Partial 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.