URL parser

This page runs new URL(input) or new URL(input, base) from the WHATWG URL Standard. It splits host, path, query, and fragment, then applies UTS #46 ToASCII to a special-URL host. It does not call encodeURI on the whole string — that ECMA-262 encoder lives on the URL encoder and never looks at scheme or host. For the longer comparison, see WHATWG new URL vs encodeURI: Punycode vs Percent-Encoding.

Parse of https://user:pass@example.com:8080/docs?q=hello world#intro writes that sample href. Host NFC é and NFD e + U+0301 both become xn--9ca.example here because UTS #46 runs NFC first; encodeURI keeps those two host encodings distinct. This page is not encodeURIComponent and not a fetch. Form-style query pairs (space → +) belong on URLSearchParams; UTS #46 on a host string belongs on IDNA; RFC 3492 without a URL split belongs on Punycode.

The snippets below split an absolute URL into host, path, query, and fragment. Node's new URL() is the same WHATWG URL Standard this page uses. CPython urllib.parse.urlsplit is RFC 3986-style — the stdlib has no WHATWG parser. For how WHATWG parsing differs from percent-encoding a string, see WHATWG new URL vs encodeURI: Punycode vs Percent-Encoding.

const url = new URL('https://example.com:8080/docs?q=hello world#intro');
url.href
// "https://example.com:8080/docs?q=hello%20world#intro"
url.host
// "example.com:8080"
url.pathname
// "/docs"
url.search
// "?q=hello%20world"
url.hash
// "#intro"

const relative = new URL('/docs', 'https://example.com');
relative.href
// "https://example.com/docs"

from urllib.parse import urlsplit, urljoin

parts = urlsplit('https://example.com:8080/docs?q=hello world#intro')
# SplitResult(scheme='https', netloc='example.com:8080',
#             path='/docs', query='q=hello world', fragment='intro')
parts.port
# 8080
parts.query
# 'q=hello world'
parts.geturl()
# 'https://example.com:8080/docs?q=hello world#intro'

urljoin('https://example.com', '/docs')
# 'https://example.com/docs'

geturl() keeps the space in the query; this page and Node serialize ?q=hello%20world. WHATWG applies IDNA to the hostname (bücher.de → xn--bcher-kva.de) and drops default ports (https://example.com:443 serializes without :443). urlsplit keeps the Unicode host and the :443. Percent-encode a string on the URL encoder; form-style query pairs belong on URLSearchParams.

This page still calls new URL(input) or new URL(input, base) and maps a thrown TypeError to the message above. WHATWG URL.parse is the same API URL parser: success is a URL object; failure is null, not a throw. URL.canParse returns the boolean for those same inputs. Confirmed here with Node 22.14. CPython has no URL.parse — urllib.parse.urlsplit is the RFC 3986 split in the section above, not this method. Node require('node:url').parse is the legacy helper this page already warns against; it is not the WHATWG static method. For how WHATWG parsing differs from percent-encoding a string, see WHATWG new URL vs encodeURI: Punycode vs Percent-Encoding.

const sample = 'https://user:pass@example.com:8080/docs?q=hello world#intro';
const parsed = URL.parse(sample);
parsed.href
// "https://user:pass@example.com:8080/docs?q=hello%20world#intro"

URL.parse('not a url')
// null
URL.parse('/docs')
// null
URL.parse('/docs', 'https://example.com').href
// "https://example.com/docs"

URL.canParse(sample)
// true
URL.canParse('/docs')
// false

Legacy url.parse('not a url') returns an object whose href is not%20a%20url— not null and not a throw. url.parse('https://example.com:443/docs') keeps :443; this page and URL.parse drop it. urlsplit('not a url') is a SplitResult with path not a url. There is no POSIX or jq WHATWG parser — curl --url-query belongs on URLSearchParams, and %{url.host} is a curl write-out, not this parser. IDNA on a host string belongs on IDNA.