# Punycode / IDN API
> Convert internationalized domain names (IDNs) between their human-readable Unicode form and the ASCII Punycode form (xn--…) that DNS actually uses. Encode a Unicode domain like münchen.de or 例え.jp (or even an emoji label like ☕.example) to ASCII, decode an xn-- domain back to Unicode, and convert a whole URL's host in either direction. Handles accents, non-Latin scripts and emoji. Useful for IDN domain handling, email and URL validation, DNS tooling, and spotting homograph / look-alike domains. Pure local IDNA conversion — no key, no third-party service, instant. Live. 4 endpoints. Distinct from Public-Suffix-List domain parsing and from generic text encoders.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/punycode-api/..."
```

## Pricing
- **Free** (Free) — 1,280 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 17,000 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 160,000 calls/Mo, 20 req/s
- **Mega** ($60/Mo) — 820,000 calls/Mo, 50 req/s

## Endpoints

### IDN

#### `GET /v1/decode` — Punycode to Unicode

**Parameters:**
- `domain` (query, required, string) — xn-- domain Example: `xn--mnchen-3ya.de`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/punycode-api/v1/decode?domain=xn--mnchen-3ya.de"
```

**Response:**
```json
{
    "data": {
        "input": "xn--mnchen-3ya.de",
        "changed": true,
        "unicode": "münchen.de",
        "was_punycode": true
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:54.715Z",
        "request_id": "799ce861-9731-42cd-a186-2ef37d61fa81"
    },
    "status": "ok",
    "message": "Punycode to Unicode",
    "success": true
}
```

#### `GET /v1/encode` — Unicode domain to Punycode

**Parameters:**
- `domain` (query, required, string) — Unicode domain Example: `münchen.de`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/punycode-api/v1/encode?domain=m%C3%BCnchen.de"
```

**Response:**
```json
{
    "data": {
        "ascii": "xn--mnchen-3ya.de",
        "input": "münchen.de",
        "is_idn": true,
        "changed": true
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:54.813Z",
        "request_id": "0efda403-259c-4af4-bc26-207c280c00f4"
    },
    "status": "ok",
    "message": "Unicode domain to Punycode",
    "success": true
}
```

#### `GET /v1/url` — Convert a URL host

**Parameters:**
- `url` (query, required, string) — Full URL Example: `https://例え.jp/path`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/punycode-api/v1/url?url=https%3A%2F%2F%E4%BE%8B%E3%81%88.jp%2Fpath"
```

**Response:**
```json
{
    "data": {
        "input": "https://例え.jp/path",
        "is_idn": true,
        "protocol": "https",
        "ascii_url": "https://xn--r8jz45g.jp/path",
        "hostname_ascii": "xn--r8jz45g.jp",
        "hostname_unicode": "例え.jp"
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:54.906Z",
        "request_id": "259b8042-aa45-41ae-aefd-745fc0c3655a"
    },
    "status": "ok",
    "message": "Convert a URL host",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/punycode-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "Punycode / IDN API",
        "note": "Convert internationalized domain names between Unicode and Punycode (ASCII, xn--). /v1/encode?domain=münchen.de → xn--mnchen-3ya.de ; /v1/decode?domain=xn--mnchen-3ya.de → münchen.de ; /v1/url?url= converts a full URL's host. Handles accents, non-Latin scripts and emoji labels. Useful for IDN domains, email/URL validation and homograph awareness. Instant, nothing stored.",
        "source": "Local IDNA conversion (punycode) — no key, no upstream",
        "endpoints": 4
    },
    "meta": {
        "timestamp": "2026-06-02T16:51:55.008Z",
        "request_id": "42f38dc5-3c0d-47ba-b04d-872bb46b19ad"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/punycode-api
OpenAPI spec: https://www.oanor.com/api/punycode-api/openapi.json