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
Query parameters
| Name | Type | Description |
|---|---|---|
| name (required) | string | A domain, label or URL, in Unicode or punycode. |
Response
| Name | Type | Description |
|---|---|---|
| tool (required) | string | |
| target (required) | string | |
| status (required) | "ok" | "partial" | "error" | |
| fetched_at | string | |
| cached | boolean | |
| credits_used | integer | Credits 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 | |
| score | integer or null | |
| findings | array of object | |
| credits_remaining (required) | integer | Your balance after this call. It can be below zero after a refund; free tools still work then |
| data (required) | object | This 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 null | The 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 object | Non-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 null | The ASCII name this one can pass for, if any. |
| data.transitional_ascii (required) | string or null | What 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 "https://api.dnssuper.com/v1/idn?name=b%C3%BCcher.example" \
-H "Authorization: Bearer $DNSSUPER_API_KEY"Python
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
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
{
"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
{
"tool": "convert_idn",
"arguments": {
"name": "bücher.example"
}
}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