Extracts the subdomain component of a URL.
get_subdomain(
url,
protocol_handling = "keep",
www_handling = "none",
source = c("all", "private", "icann"),
include_www = FALSE,
format = c("string", "labels"),
host_encoding = c("keep", "idna", "unicode"),
scheme_policy = c("infer", "require"),
scheme_acceptance = c("web", "general"),
url_standard = NULL,
engine = NULL
)A character vector (format="string") or list of label vectors (format="labels").
A character vector of URLs.
A character string specifying how to handle
protocols. Defaults to "keep".
Regardless of this option, rurl only processes authority-based URLs whose
scheme is one of http, https, ftp, or ftps; a scheme-bearing input with any
other scheme (e.g. mailto:, tel:, ws:) yields
parse_status = "error". Scheme inference (below) also requires the
input to be host-shaped: a scheme-less string that is not a host (e.g.
"asdfghjkl", "12345", "/path") or is a non-canonical
IP literal (integer/hex/octal/short forms, or leading-zero octets like
"192.168.010.1") is rejected as "error" rather than having a
scheme fabricated for it.
"keep": If a supported scheme exists (http, https, ftp, ftps), it's
used. If no scheme and the input is host-shaped, "http://" is added;
otherwise the input is not a URL and yields "error".
"none": If a supported scheme exists, it's used. If no scheme, then no scheme is used (scheme component will be NA).
"strip": Any existing scheme is removed (scheme component will be NA).
"http": The scheme is forced to be "http".
"https": The scheme is forced to be "https".
A character string specifying how to handle "www"
and www[number] prefixes in the host. Defaults to "none".
"none": (Default) Leaves the host's www prefix (or lack thereof) untouched.
"strip": Removes any "www." or www[number]. prefix.
"keep": Ensures the host starts with "www.". If it has
www[number]., it's normalized to "www.". If no www prefix, "www." is
added. An empty input host remains empty.
"if_no_subdomain": If the host is a bare registered domain (e.g.,
"example.com"), "www." is added. If the host already has a "www." or
www[number]. prefix, it is normalized to "www." (e.g.,
"www1.example.com" becomes "www.example.com"; "www1.sub.example.com"
becomes "www.sub.example.com"). If a non-www subdomain exists (e.g.,
"sub.example.com" or the normalized "www.sub.example.com"), the host is
not further altered. An empty input host remains empty.
Which PSL source to use: "all", "private", or "icann".
Logical; if FALSE (default), removes a leading
www/www[0-9]* label only when it is the sole subdomain label.
Return format: "string" (default) or "labels" for a character vector of labels.
How to present the host in clean_url. Defaults to
"keep".
"keep": Leave the host as parsed (may preserve original case).
"idna": Convert Unicode host labels to Punycode (IDNA) for the cleaned URL.
"unicode": Decode Punycode labels to Unicode for the cleaned URL.
Under url_standard = "whatwg" every value renders the UTS-46-mapped
host, because mapping is part of WHATWG host parsing rather than a
feature of the idna dial (BÜCHER.example presents as
bücher.example; RUL-002). There "keep" preserves only whether the
input was written as an A-label (xn--...), so get_host() and
get_domain() agree on the same row. "rfc3986" and NULL are
unaffected.
Controls whether scheme-less, host-shaped input is
accepted (an input-acceptance axis, distinct from protocol_handling,
which only controls how the scheme is presented, and from url_standard,
which controls interpretation). Defaults to "infer".
"infer": (Default) Fabricate http:// for scheme-less host-shaped
input (e.g. example.com parses as http://example.com), a
browser-omnibox-style affordance. This is the historical behavior.
"require": Reject scheme-less input — a scheme-less host-shaped
value becomes parse_status = "error" rather than gaining a fabricated
scheme. Use this for a strict, pure-parser posture. Note this governs
only bare host input; scheme-relative //host input is governed
separately by scheme_relative_handling.
Which scheme tokens may enter parsing (a
scheme-acceptance axis, distinct from scheme_policy, which governs
scheme-less input, and from url_standard, which governs interpretation).
Defaults to "web".
"web": (Default) Only the curated web-scheme allowlist
(http/https/ftp/ftps/file) is admitted; a scheme-bearing input
outside it is parse_status = "error". This is the historical,
byte-for-byte compatible behavior.
"general": Admit any syntactically valid scheme token and parse
opaque (mailto:x), non-special (foo://host), and RFC-generic URLs.
Requires an explicit url_standard ("rfc3986" or "whatwg"), which
decides the interpretation; general with url_standard = NULL is an
error. Non-special / opaque hosts receive no www-stripping, no domain/TLD
derivation, and are never run through the IDNA/punycode helpers.
A non-special scheme with no // is an opaque path: it has no
authority, so host, user, port and the domain/tld columns are
all NA and the entire remainder is the path (query/fragment are
still split off). This includes mailto: — the recipient's @ never
re-triggers authority parsing. To decompose a mailto: recipient, use
the accessors (get_host() / get_domain() / get_user(), ADR 0012 D7)
or get_mailto_recipients(); those deliberately return a recipient's
parts where this table presents NA, because a recipient domain is
extraction metadata, not the URL's authority.
Note that file: is admitted under both values, including the default.
A file: URL denotes local-filesystem access, and one with a non-empty
host (file://server/share/x) is a UNC path on Windows, so dereferencing
it reaches a remote SMB share. rurl parses file: URLs; it never opens
them. Restricting schemes before anything dereferences them is the
caller's job — see SECURITY.md.
Optional top-level standard profile: NULL (default),
"rfc3986", or "whatwg". With NULL the behavior is exactly what the
individual low-level options select (fully backward compatible). When set,
it selects a coherent set of standard-conformant behaviors for the axes it
governs — path percent/dot handling, the host IPv4/reg-name model, and
case_handling — so callers do not have to hand-assemble the low-level
knobs. Passing a governed low-level knob (path_normalization or
case_handling) with a value the selected
profile would not choose is an error; passing the value the profile would
pick is accepted (only case_handling = "lower_host" is accepted under a
selector — "keep", "lower", and "upper" all conflict, since "lower"
also lowercases the path, which neither standard sanctions). Added as the
last argument so existing positional calls keep their meaning; always
pass it by name. Under "whatwg" the selector additionally recognizes a
literal backslash as a path separator for WHATWG-special schemes
(http/https/ftp) and nulls default ports in parse output; use
port_handling = "strip_default" for spec-style clean URL port rendering.
See resolve_url for url_standard-governed
reference resolution. The selector does not govern whether
port_handling may be set (it is a standalone editorial knob), nor does it
govern path_encoding (an orthogonal path-presentation knob that layers
on any profile), IDNA rendering, or query handling.
Optional pslr engine controlling which Public Suffix List
backs domain / TLD / subdomain extraction: NULL (default) resolves
against pslr's session-global default list — exactly the historical
behavior — while a pslr::psl_engine() snapshot resolves against that
specific list, per request, without mutating any global state (never call
pslr::psl_use() for this). Use it to pin a particular list version or to
load an alternate list via pslr::psl_engine(source = "path", path = ...).
Process-local: an engine holds a C++ external pointer that does not
serialize across R sessions or parallel workers — build it in the process
that uses it; never cache it to disk or send it to a worker (rebuild one
per process instead). Only the domain-derived outputs (domain, tld,
and the subdomain-trimmed host / clean_url) depend on it.
get_subdomain("http://www.blog.example.co.uk")
get_subdomain("http://www.blog.example.co.uk", format = "labels")
Run the code above in your browser using DataLab