Punycode Converter API

About the Punycode Converter API

A Punycode converter for international domain names. Send a Unicode domain such as münchen.de and get the xn-- form that DNS and certificates use, or send an xn-- name and get the readable Unicode back. It is essential for working with international domain names containing non-ASCII characters like accents, Chinese, Arabic, or Cyrillic, whether you are registering domains, validating signup forms or displaying links.

The response also reports which writing systems appear in the non-ASCII labels, and checks for homograph spoofing: labels that mix scripts in a way no real language does, such as a Latin 'a' swapped for a visually identical Cyrillic one. That is the pattern behind look-alike phishing domains, so security tools, email filters and link scanners can flag it before a user clicks.

The Free plan returns the converted output, whether the input was treated as a domain, and the scripts list. Paid plans add isIDN, which says whether the name actually needs Punycode, and mixedScript, the spoofing verdict.

How it works

Conversion follows the Punycode algorithm from RFC 3492. When text contains a dot it is treated as a domain: it is split into labels, and in encode mode only labels with non-ASCII characters are converted and given the xn-- prefix, while plain labels such as de are left alone. In decode mode only labels starting with xn-- are decoded. Without a dot the whole string is converted as a single label. The input is not lower-cased or normalised first, so München and münchen encode differently; normalise input before calling if you need registry-style results.

Invalid Punycode in decode mode, such as digits outside the alphabet, a truncated sequence or a value that is not a character, returns a 400 that names text. isDomain is true when the input contains a dot.

isIDN is true when the Unicode form contains a non-ASCII character or the ASCII form contains an xn-- label, so example.com returns false. scripts lists the writing systems found in labels that contain non-ASCII letters, with digits, hyphens and combining accents ignored. mixedScript is true when any label mixes scripts outside the combinations used by real languages (Japanese Han with Hiragana, Katakana and Latin; Korean Han with Hangul and Latin; Chinese Han with Bopomofo and Latin). It catches Latin-and-Cyrillic style spoofs, not same-script look-alikes such as rn for m. On the Free plan isIDN and mixedScript are null.

What people use it for

Domain Registration

Verify and convert international domain names

Web Development

Handle IDN domains in applications

Email Systems

Process internationalized email addresses

Security

Detect homograph attacks using similar-looking Unicode characters

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON

Default REST response

XML

Markup format

YAML

Human-readable

CSV

Tabular export

Beta

GraphQL

Query language

New

MCP

For AI agents

How it compares

Side by side with the tools people weigh Punycode Converter against — what each one is better at, in plain terms.

Request parameters — GET /v1/punycode

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Required

Optional

1
2

curl "https://api.apiverve.com/v1/punycode?text=m%C3%BCnchen.de&mode=encode" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Response — GET /v1/punycode

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "status": "ok",
  "error": null,
  "data": {
    "input": "münchen.de",
    "output": "xn--mnchen-3ya.de",
    "mode": "encode",
    "isIDN": true,
    "isDomain": true,
    "scripts": [
      "Latin"
    ],
    "mixedScript": false
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

What a call costs — 1 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Zero-code embed — one snippet, no backend

Drop an interactive Punycode Converter form onto any page. The widget calls the API for you, so no key ever appears in your markup and there is nothing to deploy.

Changelog — Punycode Converter API

Every change to this endpoint, newest first. Breaking changes ship as a new version and the previous one keeps serving — response fields are added, never removed or retyped in place, so an integration written against v1 keeps working.

Currently v1