Docs menu

IDN and punycode

Convert domain names between Unicode and punycode, and see which characters could fool a reader.

GET /v1/idn

Price
Free; any API key works and nothing is charged.
Cache
Never cached; every call runs again.
MCP tool
convert_idn

Run it in the browser

Query parameters

Query parameters
NameTypeDescription
name (required)stringA domain, label or URL, in Unicode or punycode.

Response

Response fields
NameTypeDescription
tool (required)string
target (required)string
status (required)"ok" | "partial" | "error"
fetched_atstring
cachedboolean
credits_usedintegerCredits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in
summary (required)string
scoreinteger or null
findingsarray of object
credits_remaining (required)integerYour balance after this call. It can be below zero after a refund; free tools still work then
data (required)objectThis tool's result
data.input (required)string
data.direction (required)"to_ascii" | "to_unicode" | "ascii_only"
data.ascii (required)string or null
data.unicode (required)string
data.valid (required)boolean
data.labels (required)array of object
data.labels.unicode (required)string
data.labels.ascii (required)string or nullThe A-label or ASCII label; null when invalid.
data.labels.valid (required)boolean
data.labels.error (required)object or null
data.labels.scripts (required)array of string
data.labels.mixed_script (required)boolean
data.labels.restriction (required)"ascii" | "single_script" | "highly_restrictive" | "moderately_restrictive" | "minimally_restrictive"
data.labels.chars (required)array of objectNon-ASCII characters, at most 63.
data.labels.skeleton (required)string
data.labels.imitates_ascii (required)boolean
data.skeleton (required)string
data.imitates (required)string or nullThe ASCII name this one can pass for, if any.
data.transitional_ascii (required)string or nullWhat IDNA 2003 (transitional) software makes of the name, when it differs.
data.display (required)object
data.display.likely (required)"unicode" | "punycode"
data.display.reason (required)string

Errors

  • 400 Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
  • 401 Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
  • 403 Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
  • 429 Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
  • 500 Unexpected error (`internal_error`)

Example

curl

curl
curl "https://api.dnssuper.com/v1/idn?name=b%C3%BCcher.example" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"

Python

Python (httpx)
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.get("/v1/idn", params={
    "name": "bücher.example",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])

TypeScript

TypeScript (fetch)
const response = await fetch(`https://api.dnssuper.com/v1/idn?${new URLSearchParams({"name":"bücher.example"})}`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
Example response
Example response
{
  "tool": "punycode-converter",
  "target": "",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 0,
  "summary": "bücher.example in punycode is xn--bcher-kva.example.",
  "findings": [],
  "data": {
    "input": "bücher.example",
    "direction": "to_ascii",
    "ascii": "xn--bcher-kva.example",
    "unicode": "bücher.example",
    "valid": true,
    "labels": [
      {
        "unicode": "bücher",
        "ascii": "xn--bcher-kva",
        "valid": true,
        "scripts": [
          "Latin"
        ],
        "mixed_script": false,
        "restriction": "single_script",
        "chars": [
          {
            "char": "ü",
            "codepoint": "U+00FC",
            "name": "LATIN SMALL LETTER U WITH DIAERESIS",
            "scripts": [
              "Latin"
            ],
            "identifier": "allowed"
          }
        ],
        "skeleton": "bücher",
        "imitates_ascii": false
      },
      {
        "unicode": "example",
        "ascii": "example",
        "valid": true,
        "scripts": [
          "Latin"
        ],
        "mixed_script": false,
        "restriction": "ascii",
        "chars": [],
        "skeleton": "exarnple",
        "imitates_ascii": false
      }
    ],
    "skeleton": "bücher.exarnple",
    "display": {
      "likely": "unicode",
      "reason": "Each label sticks to one writing system without lookalikes, so browsers will likely show it in Unicode."
    }
  },
  "credits_remaining": 498
}

MCP

MCP tool call
{
  "tool": "convert_idn",
  "arguments": {
    "name": "bücher.example"
  }
}
Compact MCP output
bücher.example in punycode is xn--bcher-kva.example.
ASCII: xn--bcher-kva.example
Unicode: bücher.example
Label 1: Latin, single script, 1 non-ASCII character
Label 2: plain ASCII
Browsers will likely show: unicode (Each label sticks to one writing system without lookalikes, so browsers will likely show it in Unicode.)
No issues found.
Free | checked 2026-11-14 10:00 UTC