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
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | Chrome
Full support
32
| Edge Full support 12 | Firefox
Full support
19
| IE Full support 10 | Opera
Full support
19
| Safari
Full support
7
| WebView Android
Full support
4.4
| Chrome Android
Full support
32
| Firefox Android
Full support
19
| Opera Android
Full support
19
| Safari iOS
Full support
7
| Samsung Internet Android
Full support
2.0
|
URL() constructor | Chrome Full support 19 | Edge Full support 12 | Firefox Full support 26 | IE No support No | Opera Full support 15 | Safari Full support 6 | WebView Android Full support ≤37 | Chrome Android Full support 25 | Firefox Android Full support 26 | Opera Android Full support 14 | Safari iOS Full support 6 | Samsung Internet Android Full support 1.5 |
createObjectURL | Chrome Full support 19 | Edge Full support 12 | Firefox
Full support
19
| IE
Full support
10
| Opera Full support 15 | Safari Full support 6 | WebView Android Full support Yes | Chrome Android Full support 25 | Firefox Android
Full support
19
| 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
| 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 |
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
| 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
| 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 | Chrome Full support 19 | Edge Full support 12 | Firefox
Full support
19
| 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
| 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
| 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
| 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
- 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.