ua-phone

Tiny zero-dependency utilities for Ukrainian phone numbers: normalization, canonical grouping keys, display formatting, mobile-operator detection by prefix and landline area codes.

Built and battle-tested at ktozvonil.net — a community phone-number reputation service processing millions of lookups.

Install

npm install ua-phone

Quick start

import { uaInfo, uaOperator, formatDisplay, groupKey, normalize } from "ua-phone";

uaInfo("+38 073 111 22 33");
// {
//   national: "0731112233",
//   e164: "380731112233",
//   prefix: "073",
//   kind: "mobile",
//   operator: "lifecell",
//   area: null
// }

uaInfo("0441234567");
// { kind: "landline", area: { uk: "Київ", en: "Kyiv" }, ... }

uaOperator("0671234567");     // "Kyivstar"
formatDisplay("380501108901"); // "+380 50 110 89 01"
groupKey("050 110-89-01");     // "380501108901"  (same key for any format)
normalize("+38 (050) 110-89-01"); // "380501108901"

API

| Function | Description | |----------|-------------| | normalize(raw) | Digits only; null if implausible length (7–15) | | groupKey(phone) | Canonical key — format-siblings of one physical number share it (380… for UA, 7… for RU) | | toNational(phone) | 0XXYYYYYYY national form, null if not Ukrainian | | formatDisplay(phone) | Pretty-printing for UI | | uaInfo(phone) | Full classification: kind (mobile/landline/toll-free/premium), operator, area | | uaOperator(phone) | Operator shortcut | | UA_MOBILE_OPERATORS | Prefix → operator map (data export) | | UA_AREA_CODES | Area code → oblast centre map, uk + en names (data export) |

The MNP caveat

Ukraine has had mobile number portability since 2019: a prefix identifies the operator the range was allocated to, not necessarily the current one. For most numbers they coincide; when you need the authoritative answer, query the УЦМЗ registry. This library intentionally stays offline and returns the allocation.

Related

• ktozvonil.net — check who called from any number (community reviews, spam verdicts)
• mcp-server-ktozvonil — let AI assistants look up numbers via MCP

License

MIT © ktozvonil.net