W3cubDocs

/Web APIs

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.

Note: This feature is available in Web Workers

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.

js

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:

js

let myUsername = "someguy";
let addr = new URL("https://example.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://example.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:

js

let addr = new URL("https://example.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:

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.

js

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

  for (const key of keys) {
    const val = url.searchParams.get(key);
    const row = document.createElement("tr");
    const cell1 = document.createElement("td");
    cell1.innerText = key;
    row.appendChild(cell1);
    const cell2 = document.createElement("td");
    cell2.innerText = val;
    row.appendChild(cell2);
    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
URL Standard
# api

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
URL 19
12Before Edge 79, query arguments in the base URL argument are removed when calling the URL constructor.
26 No 15 14.1
6In 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.
4.4 25 26 14 14.5
6In 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.
1.5
URL_API 3219 12
19Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
10 1915 76 4.44 3225
19Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
1914 76 2.01.5
canParse_static No No 115 No No 17 No No 115 No 17 No
createObjectURL_static 19 12
19createObjectURL() is no longer available within the context of a ServiceWorker.
10If 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.
15 6 4.4 25
19createObjectURL() is no longer available within the context of a ServiceWorker.
14 6 1.5
hash 32 13 22 No 19 7 4.4.3 32 22 19 7 2.0
host 32 13 22 No 19 7 4.4.3 32 22 19 7 2.0
hostname 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
href 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
origin 32 12 26
26–49Results for URL using the blob scheme incorrectly returned null.
No 19 10 4.4.3 32 26
26–49Results for URL using the blob scheme incorrectly returned null.
19 10 6.0
password 32 12 26 No 19 10 4.4.3 32 26 19 10 6.0
pathname 32 13
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
No 19 10 4.4.3 32
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
19 10 2.0
port 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
protocol 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
revokeObjectURL_static 19 12
19revokeObjectURL() is no longer available within the context of a ServiceWorker.
10 15 6 4.4 25
19revokeObjectURL() is no longer available within the context of a ServiceWorker.
14 6 1.5
search 32 13
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
No 19 10 4.4.3 32
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
19 10 2.0
searchParams 51 17 29 No 38 10.1 51 51 29 41 10.3 5.0
toJSON 71 17 54 No 58 11 71 71 54 50 11 10.0
toString 19 17 54 No 15 7 4.4 25 54 14 7 6.0
username 32 12 26 No 19 10 4.4.3 32 26 19 10 6.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URL_API