IDN Variants (idn_variants)

Overview

datapulse_idn_variants computes the variant set of an internationalized label under ICANN’s Root Zone Label Generation Rules (RZ-LGR 6, 23 September 2025). These rules decide which variants of an IDN top-level domain may be delegated, and the 2026 New gTLD round evaluates IDN strings under them.

Two kinds of variant come back:

The set has two sources, as ICANN uses them:

• The label’s Element LGR (the rules for its script) gives its allocatable and blocked variants within that script, such as the traditional and simplified forms of a Chinese label.
• The Common LGR holds every collision across scripts, and every variant in it is blocked. Its variants that the Element LGR does not list are added as blocked with common_lgr: true. They are often the majority: the Japanese rules relate 集團 only to 集団, while the Common LGR also blocks the Chinese forms 集团 and 集糰. The Korean rules relate it to nothing, so all three come from the Common LGR.

Two flags describe each variant, and they are independent:

• cross_script: true: the variant is written, wholly or partly, in a script the label does not use. paypal has 2,242 such variants (its Cyrillic lookalikes such as раураӏ, and Latin–Cyrillic mixes), all listed by the Latin rules themselves.
• common_lgr: true: only the Common LGR gives the label this variant. For 集團 under the Korean rules all three variants are common_lgr, yet none is cross_script: they are Han like the label.

The rules are root-zone policy, but the relationships they encode (Chinese character forms, Cyrillic, Greek and Latin lookalikes, Arabic letter shapes) are a sound, sourced guide to confusable second-level names as well. Use them that way for lookalike and impersonation work, saying that the variant set is defined by the root-zone rules.

The computation is local and makes no lookups. It only tells you which names are variants, not whether any of them are registered.

Parameters

Leftmost label only. For a domain name, only the leftmost label is varied, and each variant is reassembled with the remaining labels unchanged: 集团.com gives 集團.com, 集糰.com and 集団.com. For www.集团.中国 the varied label is www, and the note says so whenever IDN labels follow it. To get the variants of a TLD or of a label further right, pass that label alone.

Han ideographs. A label of Han characters only can be valid under more than one of the Chinese, Japanese and Korean rules, which give different variant sets: 山 under all three, 中国 under Chinese and Japanese (Korean lacks 国). When more than one accepts the label, the call is refused and the error names exactly those that do. Call again with script set to one of them, according to the language the name is meant in. Labels containing kana are Japanese and labels containing hangul are Korean, so those are detected without help.

Response Format

{
  "input": "集团.com",
  "label": "集团",
  "label_ascii": "xn--3bst00m",
  "domain": "集团.com",
  "domain_ascii": "xn--3bst00m.com",
  "script": "chinese",
  "lgr_data": "rz-lgr-6-common-23sep25-en.xml",
  "complete": true,
  "total": 3,
  "counts": {"allocatable": 2, "blocked": 1, "other": 0, "rejected": 0, "cross_script": 0, "whole_script": 0, "common_lgr": 0},
  "returned": 3,
  "allocatable": [
    {"label": "集團", "ascii": "xn--ndsv59l", "domain_ascii": "xn--ndsv59l.com", "code_points": "U+96C6 U+5718", "scripts": ["Han"]},
    {"label": "集糰", "ascii": "xn--g9z124c", "domain_ascii": "xn--g9z124c.com", "code_points": "U+96C6 U+7CF0", "scripts": ["Han"]}
  ],
  "blocked": [
    {"label": "集団", "ascii": "xn--4bsr00m", "domain_ascii": "xn--4bsr00m.com", "code_points": "U+96C6 U+56E3", "scripts": ["Han"]}
  ]
}

Variants the rules mark invalid (a combination a context or whole-label rule forbids) are not variants at all and are never listed, as in ICANN’s reference implementation.

Order and paging

Results come in pages of limit variants, in one fixed order:

1. allocatable variants;
2. blocked variants written wholly in a script the label does not use: the whole-script lookalikes, the most deceptive kind (раураӏ, all Cyrillic, for paypal);
3. blocked variants written wholly in the label’s own script (paypál);
4. blocked variants that mix scripts;
5. any other disposition.

Each group is sorted by label, and rejected variants come last within their disposition. The same offset always returns the same page. Walk the set by passing each page’s next_offset until truncated is absent. A page with truncated: true is a subset, not the whole variant set; total and counts describe the whole set.

Size and limits

• Sizes vary widely. Many labels have no variants. A Cyrillic or Greek label has tens to a few hundred (москва 299, католик 399). A Latin label grows with its length: google 1,599, amazon 1,999, paypal 2,249, microsoft 50,399. Read the first page and counts before deciding to walk the rest; for a brand check, the whole-script lookalikes on page 1 usually matter most.
• 100,000 variants at most. Generation stops there with complete: false. It varies the end of the label first, so the variants that change its first letters, whole-script lookalikes among them, are the likeliest to be missing from an incomplete set. An incomplete set is not every variant. A full set this size takes a few seconds to compute.
• Letters only. The RZ-LGR repertoire has no digits and no hyphen, because neither is allowed in a TLD. A label containing either (abc123, my-brand) is refused, and the error names the character and its position, counting from 1. Such names have no RZ-LGR variant set.
• One script per label. A label mixing scripts (Latin p with Cyrillic а in pаl) is refused: the rules give it no variant set, though such labels appear among the variants of single-script ones. A mixed-script label is usually itself a lookalike; pass the single-script name it imitates, or find registered lookalikes with datapulse_dns_searchlabels. See datapulse_help(topic="typo_squatting").
• script must fit the label. With script set, a label the chosen rules do not accept is refused, and the error says to omit script to use the label’s own rules.

Workflow: which variants are registered?

1. datapulse_idn_variants(domain="集团.com"), paging with next_offset if truncated is set
2. Send the domain_ascii values to datapulse_live_rdap_bulk (or datapulse_live_dns_bulk), one {"query": "<domain_ascii>"} item each.
3. Read each result back with datapulse_live_rdap(domain_hash=...), then compare registrar, creation date and nameservers against the original (registrant data is GDPR-redacted; see datapulse_help(topic="registrant_lookup")).

An allocatable variant held by an unrelated party, or any blocked variant registered at all under a second-level registry that does not apply the same rules, deserves a closer look. Corroborate before calling either one abuse: some brands register their own variants defensively.

datapulse_dns_searchlabels finds lookalikes that are already in the corpus by fuzzy match. This tool instead lists, from the published rules, every name that counts as a variant, whether or not it exists. The two complement each other.