The `url` module provides utilities for URL resolution and parsing. It can be

accessed using:

```js

const url = require('url');

```

A URL string is a structured string containing multiple meaningful components.

When parsed, a URL object is returned containing properties for each of these

components.

The following details each of the components of a parsed URL. The example

`'http://user:[email protected]:8080/p/a/t/h?query=string#hash'` is used to

illustrate each.

┌─────────────────────────────────────────────────────────────────────────────────┐

│ href │

├──────────┬┬───────────┬─────────────────────┬───────────────────────────┬───────┤

│ protocol ││ auth │ host │ path │ hash │

│ ││ ├──────────────┬──────┼──────────┬────────────────┤ │

│ ││ │ hostname │ port │ pathname │ search │ │

│ ││ │ │ │ ├─┬──────────────┤ │

│ ││ │ │ │ │ │ query │ │

" http: // user:pass @ sub.host.com : 8080 /p/a/t/h ? query=string #hash "

│ ││ │ │ │ │ │ │ │

└──────────┴┴───────────┴──────────────┴──────┴──────────┴─┴──────────────┴───────┘

The `auth` property is the username and password portion of the URL, also

referred to as "userinfo". This string subset follows the `protocol` and

double slashes (if present) and precedes the `host` component, delimited by an

ASCII "at sign" (`@`). The format of the string is `{username}[:{password}]`,

with the `[:{password}]` portion being optional.

The `hash` property consists of the "fragment" portion of the URL including

the leading ASCII hash (`#`) character.

The `host` property is the full lower-cased host portion of the URL, including

the `port` if specified.

The `hostname` property is the lower-cased host name portion of the `host`

component *without* the `port` included.

The `href` property is the full URL string that was parsed with both the

`protocol` and `host` components converted to lower-case.

For example: `'http://user:[email protected]:8080/p/a/t/h?query=string#hash'`

### urlObject.path

The `path` property is a concatenation of the `pathname` and `search`

components.

For example: `'/p/a/t/h?query=string'`

No decoding of the `path` is performed.

The `pathname` property consists of the entire path section of the URL. This

is everything following the `host` (including the `port`) and before the start

of the `query` or `hash` components, delimited by either the ASCII question

mark (`?`) or hash (`#`) characters.

### urlObject.query

The `query` property is either the query string without the leading ASCII

question mark (`?`), or an object returned by the [`querystring`][] module's

`parse()` method. Whether the `query` property is a string or object is

determined by the `parseQueryString` argument passed to `url.parse()`.

If returned as a string, no decoding of the query string is performed. If

returned as an object, both keys and values are decoded.

The `search` property consists of the entire "query string" portion of the

URL, including the leading ASCII question mark (`?`) character.

For example: `'?query=string'`

No decoding of the query string is performed.

### urlObject.slashes

The `slashes` property is a `boolean` with a value of `true` if two ASCII

forward-slash characters (`/`) are required following the colon in the

`protocol`.

## url.format(urlObject)

<!-- YAML

added: v0.1.25

-->

constructed otherwise). If a string, it is converted to an object by passing

it to `url.parse()`.

The `url.format()` method returns a formatted URL string derived from

`urlObject`.

If `urlObject` is not an object or a string, `url.parse()` will throw a

[`TypeError`][].

The formatting process operates as follows:

* A new empty string `result` is created.

* If `urlObject.protocol` is a string, it is appended as-is to `result`.

* Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an

[`Error`][] is thrown.

* For all string values of `urlObject.protocol` that *do not end* with an ASCII

colon (`:`) character, the literal string `:` will be appended to `result`.

* If either of the following conditions is true, then the literal string `//`

will be appended to `result`:

* `urlObject.slashes` property is true;

* `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or

`file`;

* If the value of the `urlObject.auth` property is truthy, and either

`urlObject.host` or `urlObject.hostname` are not `undefined`, the value of

`urlObject.auth` will be coerced into a string and appended to `result`

followed by the literal string `@`.

* If the `urlObject.host` property is `undefined` then:

* If the `urlObject.hostname` is a string, it is appended to `result`.

* Otherwise, if `urlObject.hostname` is not `undefined` and is not a string,

an [`Error`][] is thrown.

* If the `urlObject.port` property value is truthy, and `urlObject.hostname`

is not `undefined`:

* The literal string `:` is appended to `result`, and

* The value of `urlObject.port` is coerced to a string and appended to

`result`.

* Otherwise, if the `urlObject.host` property value is truthy, the value of

`urlObject.host` is coerced to a string and appended to `result`.

* If the `urlObject.pathname` property is a string that is not an empty string:

* If the `urlObject.pathname` *does not start* with an ASCII forward slash

(`/`), then the literal string '/' is appended to `result`.

* The value of `urlObject.pathname` is appended to `result`.

* Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an

[`Error`][] is thrown.

* If the `urlObject.search` property is `undefined` and if the `urlObject.query`

property is an `Object`, the literal string `?` is appended to `result`

followed by the output of calling the [`querystring`][] module's `stringify()`

method passing the value of `urlObject.query`.

* Otherwise, if `urlObject.search` is a string:

* If the value of `urlObject.search` *does not start* with the ASCII question

mark (`?`) character, the literal string `?` is appended to `result`.

* The value of `urlObject.search` is appended to `result`.

* Otherwise, if `urlObject.search` is not `undefined` and is not a string, an

[`Error`][] is thrown.

* If the `urlObject.hash` property is a string:

* If the value of `urlObject.hash` *does not start* with the ASCII hash (`#`)

character, the literal string `#` is appended to `result`.

* The value of `urlObject.hash` is appended to `result`.

* Otherwise, if the `urlObject.hash` property is not `undefined` and is not a

string, an [`Error`][] is thrown.

* `result` is returned.

## url.format(URL[, options])

> Stability: 1 - Experimental

* `URL` {URL} A [WHATWG URL][] object

* `options` {Object}

search query, `false` otherwise. Defaults to `true`.

* `unicode` (Boolean) `true` if Unicode characters appearing in the host

component of the URL string should be encoded directly as opposed to being

Punycode encoded. Defaults to `false`.

Returns a customizable serialization of a URL String representation of a

[WHATWG URL][] object.

The URL object has both a `toString()` method and `href` property that return

string serializations of the URL. These are not, however, customizable in

any way. The `url.format(URL[, options])` method allows for basic customization

of the output.

For example:

```js

const myURL = new URL('https://a:b@你好你好?abc#foo');

console.log(myURL.href);

// Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(myURL.toString());

// Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(url.format(myURL, {fragment: false, unicode: true, auth: false}));

// Prints 'https://你好你好?abc'

```

*Note*: This variation of the `url.format()` method is currently considered to

be experimental.

## url.parse(urlString[, parseQueryString[, slashesDenoteHost]])

<!-- YAML

added: v0.1.25

-->

* `urlString` {string} The URL string to parse.

* `parseQueryString` {boolean} If `true`, the `query` property will always

be set to an object returned by the [`querystring`][] module's `parse()`

method. If `false`, the `query` property on the returned URL object will be an

unparsed, undecoded string. Defaults to `false`.

For instance, given `//foo/bar`, the result would be

`{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`.

Defaults to `false`.

The `url.parse()` method takes a URL string, parses it, and returns a URL

object.

A `TypeError` is thrown if `urlString` is not a string.

A `URIError` is thrown if the `auth` property is present but cannot be decoded.

<!-- YAML

added: v0.1.25

changes:

- version: v6.6.0

pr-url: https://github.com/nodejs/node/pull/8215

description: The `auth` fields are now kept intact when `from` and `to`

refer to the same host.

- version: v6.5.0, v4.6.2

pr-url: https://github.com/nodejs/node/pull/8214

description: The `port` field is copied correctly now.

- version: v6.0.0

pr-url: https://github.com/nodejs/node/pull/1480

description: The `auth` fields is cleared now the `to` parameter

contains a hostname.

* `from` {string} The Base URL being resolved against.

* `to` {string} The HREF URL being resolved.

The `url.resolve()` method resolves a target URL relative to a base URL in a

manner similar to that of a Web browser resolving an anchor tag HREF.

For example:

```js

url.resolve('/one/two/three', 'four') // '/one/two/four'

url.resolve('http://example.com/', '/one') // 'http://example.com/one'

url.resolve('http://example.com/one', '/two') // 'http://example.com/two'

```

## Escaped Characters

URLs are only permitted to contain a certain range of characters. Spaces (`' '`)

and the following characters will be automatically escaped in the

properties of URL objects:

< > " ` \r \n \t { } | \ ^ '

```

For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII

forward slash (`/`) character is encoded as `%3C`.

## The WHATWG URL API

> Stability: 1 - Experimental

The `url` module provides an *experimental* implementation of the

[WHATWG URL Standard][] as an alternative to the existing `url.parse()` API.

```js

const URL = require('url').URL;

const myURL = new URL('https://example.org/foo');

console.log(myURL.href); // https://example.org/foo

console.log(myURL.protocol); // https:

console.log(myURL.hostname); // example.org

console.log(myURL.pathname); // /foo

```

*Note*: Using the `delete` keyword (e.g. `delete myURL.protocol`,

`delete myURL.pathname`, etc) has no effect but will still return `true`.

A comparison between this API and `url.parse()` is given below. Above the URL

`'http://user:[email protected]:8080/p/a/t/h?query=string#hash'`, properties of an

object returned by `url.parse()` are shown. Below it are properties of a WHATWG

`URL` object.

*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not

`username` or `password`.

```txt

┌─────────────────────────────────────────────────────────────────────────────────────────┐

│ href │

├──────────┬──┬─────────────────────┬─────────────────┬───────────────────────────┬───────┤

│ protocol │ │ auth │ host │ path │ hash │

│ │ │ ├──────────┬──────┼──────────┬────────────────┤ │

│ │ │ │ hostname │ port │ pathname │ search │ │

│ │ │ │ │ │ ├─┬──────────────┤ │

│ │ │ │ │ │ │ │ query │ │

" http: // user : pass @ host.com : 8080 /p/a/t/h ? query=string #hash "

│ │ │ │ │ hostname │ port │ │ │ │

│ │ │ │ ├──────────┴──────┤ │ │ │

│ protocol │ │ username │ password │ host │ │ │ │

├──────────┴──┼──────────┴──────────┼─────────────────┤ │ │ │

│ origin │ │ origin │ pathname │ search │ hash │

├─────────────┴─────────────────────┴─────────────────┴──────────┴────────────────┴───────┤

│ href │

└─────────────────────────────────────────────────────────────────────────────────────────┘

(all spaces in the "" line should be ignored -- they are purely for formatting)

```

### Class: URL

#### Constructor: new URL(input[, base])

absolute.

Creates a new `URL` object by parsing the `input` relative to the `base`. If

`base` is passed as a string, it will be parsed equivalent to `new URL(base)`.

```js

const myURL = new URL('/foo', 'https://example.org/');

// https://example.org/foo

```

A `TypeError` will be thrown if the `input` or `base` are not valid URLs. Note

that an effort will be made to coerce the given values into strings. For

instance:

```js

const myURL = new URL({toString: () => 'https://example.org/'});

// https://example.org/

```

Unicode characters appearing within the hostname of `input` will be

automatically converted to ASCII using the [Punycode][] algorithm.

```js

const myURL = new URL('https://你好你好');

```

Additional [examples of parsed URLs][] may be found in the WHATWG URL Standard.

#### url.hash

Gets and sets the fragment portion of the URL.

```js

const myURL = new URL('https://example.org/foo#bar');

console.log(myURL.hash);

// Prints #bar

myURL.hash = 'baz';

console.log(myURL.href);

// Prints https://example.org/foo#baz

```

Invalid URL characters included in the value assigned to the `hash` property

are [percent-encoded][]. Note that the selection of which characters to

percent-encode may vary somewhat from what the [`url.parse()`][] and

[`url.format()`][] methods would produce.

#### url.host

Gets and sets the host portion of the URL.

```js

const myURL = new URL('https://example.org:81/foo');

console.log(myURL.host);

// Prints example.org:81

myURL.host = 'example.com:82';

console.log(myURL.href);

// Prints https://example.com:82/foo

```

Invalid host values assigned to the `host` property are ignored.

#### url.hostname

Gets and sets the hostname portion of the URL. The key difference between

`url.host` and `url.hostname` is that `url.hostname` does *not* include the

port.

```js

const myURL = new URL('https://example.org:81/foo');

console.log(myURL.hostname);

// Prints example.org

myURL.hostname = 'example.com:82';

console.log(myURL.href);

// Prints https://example.com:81/foo

```

Invalid hostname values assigned to the `hostname` property are ignored.

#### url.href

Gets and sets the serialized URL.

```js

const myURL = new URL('https://example.org/foo');

console.log(myURL.href);

// Prints https://example.org/foo

myURL.href = 'https://example.com/bar'

// Prints https://example.com/bar

```

Getting the value of the `href` property is equivalent to calling

[`url.toString()`][].

Setting the value of this property to a new value is equivalent to creating a

new `URL` object using [`new URL(value)`][`new URL()`]. Each of the `URL`

object's properties will be modified.

If the value assigned to the `href` property is not a valid URL, a `TypeError`

will be thrown.

#### url.origin

Gets the read-only serialization of the URL's origin. Unicode characters that

may be contained within the hostname will be encoded as-is without [Punycode][]

encoding.

```js

const myURL = new URL('https://example.org/foo/bar?baz');

console.log(myURL.origin);

// Prints https://example.org

```

```js

const idnURL = new URL('https://你好你好');

console.log(idnURL.origin);

// Prints https://你好你好

console.log(idnURL.hostname);

// Prints xn--6qqa088eba

```

#### url.password

Gets and sets the password portion of the URL.

```js

const myURL = new URL('https://abc:[email protected]');

console.log(myURL.password);

// Prints xyz

myURL.password = '123';

console.log(myURL.href);

// Prints https://abc:[email protected]

```

Invalid URL characters included in the value assigned to the `password` property

are [percent-encoded][]. Note that the selection of which characters to

percent-encode may vary somewhat from what the [`url.parse()`][] and

[`url.format()`][] methods would produce.

#### url.pathname

Gets and sets the path portion of the URL.

```js

const myURL = new URL('https://example.org/abc/xyz?123');

console.log(myURL.pathname);

// Prints /abc/xyz

myURL.pathname = '/abcdef';

console.log(myURL.href);

// Prints https://example.org/abcdef?123

```

Invalid URL characters included in the value assigned to the `pathname`

property are [percent-encoded][]. Note that the selection of which characters

to percent-encode may vary somewhat from what the [`url.parse()`][] and

[`url.format()`][] methods would produce.

#### url.port

Gets and sets the port portion of the URL.

```js

const myURL = new URL('https://example.org:8888');

console.log(myURL.port);

// Prints 8888

// Default ports are automatically transformed to the empty string

// (HTTPS protocol's default port is 443)

myURL.port = '443';

console.log(myURL.port);

// Prints the empty string

console.log(myURL.href);

// Prints https://example.org/

console.log(myURL.port);

// Prints 1234

// Prints https://example.org:1234/

// Completely invalid port strings are ignored

myURL.port = 'abcd';

console.log(myURL.port);

// Prints 1234

// Leading numbers are treated as a port number

myURL.port = '5678abcd';

console.log(myURL.port);

// Prints 5678

// Non-integers are truncated

myURL.port = 1234.5678;

console.log(myURL.port);

// Prints 1234