BKNS Whois API

REST API tra cứu thông tin WHOIS và kiểm tra khả dụng tên miền.
Hỗ trợ 1.260+ TLD · Dữ liệu .vn từ VNNIC chính thức · Độ trễ < 200ms

Base URL https://whois.bkns.vn/api/v1

Tất cả request qua HTTPS. Phản hồi JSON, encoding UTF-8.

Xác thực

Đính kèm API key vào header X-API-Key trong mọi request. Thiếu key hoặc key sai → HTTP 401.

http

GET /api/v1/whois?domain=bkns.vn
X-API-Key: bkns_par_xxxxxxxxxxxxxxxxxx
Content-Type: application/json

⚠ Giữ API key bí mật. Không nhúng vào client-side JavaScript hay mobile app. Liên hệ [email protected] để được cấp hoặc xoay vòng key.

Rate Limits

Giới hạn request theo tier. Vượt ngưỡng → 429 Too Many Requests kèm header Retry-After.

Public

10 req/phút

Tra cứu qua UI. Không cần API key.

Partner

300 req/phút

Tích hợp server-side. Liên hệ để được cấp key.

response headers

X-RateLimit-Limit:     300
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1711234567
Retry-After:          15

GET WHOIS Lookup

Tra cứu thông tin WHOIS đầy đủ: chủ sở hữu, nhà đăng ký, ngày tạo/hết hạn, nameserver, trạng thái EPP.

GET /api/v1/whois WHOIS Lookup

Query Parameters

Tham số	Kiểu	Mô tả
domain required	string	Tên miền cần tra cứu. Chấp nhận ASCII (`bkns.vn`), punycode (`xn--...`), hoặc Unicode IDN (`münchen.de`). Tự động chuẩn hóa sang punycode.

Response

json · HTTP 200 · source: vnnic-relay

{
  "domain":            "bkns.vn",
  "tld":               "vn",
  "status":            "registered",
  "cached":            true,
  "cacheTtlRemaining": null,
  "data": {
    "registrant": {
      "name": "Công ty Cổ phần Giải pháp Mạng Bạch Kim"
    },
    "registrar": {
      "name": "Công ty cổ phần giải pháp mạng Bạch Kim"
    },
    "nameservers": ["ns1.bkdns.vn", "ns2.bkdns.vn", "ns3.bkdns.vn"],
    "dates": {
      "created":         "2010-06-24T17:00:00.000Z",
      "updated":         null,
      "expiry":          "2030-06-24T17:00:00.000Z",
      "renewalDeadline": null
    },
    "domainStatus": ["clientTransferProhibited"],
    "dnssec": false
  }
}

ℹ Chỉ có với .vn: Field data.registrant được trả về. Domain quốc tế thường không có thông tin registrant.

json · HTTP 200 · source: whois-direct

{
  "domain":            "bkns.net",
  "tld":               "net",
  "status":            "registered",
  "cached":            false,
  "cacheTtlRemaining": null,
  "data": {
    "registrar": {
      "name": "Web Commerce Communications Limited dba WebNic.cc"
    },
    "nameservers": ["carl.ns.cloudflare.com", "meg.ns.cloudflare.com"],
    "dates": {
      "created":         "2010-06-25T15:37:49Z",
      "updated":         "2026-02-02T06:32:14Z",
      "expiry":          "2027-06-25T15:37:49Z",
      "renewalDeadline": null
    },
    "domainStatus": ["ok"],
    "dnssec": false
  },
  "backendsTried": [
    { "vendorKey": "whois-direct", "success": true, "latencyMs": 675 }
  ]
}

json · HTTP 200

{
  "domain":            "example-notexist.vn",
  "tld":               "vn",
  "status":            "available",
  "cached":            false,
  "cacheTtlRemaining": null,
  "backendsTried": [
    { "vendorKey": "vnnic-relay", "success": true, "latencyMs": 145 }
  ]
}

⚠ Quan trọng: Khi status = "available", field data không tồn tại. Luôn kiểm tra status trước khi access data.*.

GET Domain Check

Kiểm tra nhanh tên miền còn khả dụng hay không. Nhanh hơn WHOIS vì chỉ trả về trạng thái.

GET /api/v1/domain/check Kiểm tra khả dụng

Query Parameters

Tham số	Kiểu	Mô tả
domain required	string	Tên miền cần kiểm tra. Chấp nhận ASCII, punycode, hoặc Unicode IDN. Tự động chuẩn hóa sang punycode.

json · HTTP 200

{
  "domain":    "example-notexist.vn",
  "tld":       "vn",
  "available": true,
  "premium":   false,
  "cached":    false
}

POST Bulk WHOIS

Tra cứu nhiều tên miền trong một request. Tối đa 20 domain/request. Yêu cầu tier Partner.

POST /api/v1/whois/bulk Bulk lookup

Request Body

json

{
  "domains": ["bkns.vn", "google.com", "example.org"]
}

Response

json · HTTP 200

{
  "results": [
    { "domain": "bkns.vn",     "status": "registered", "data": { ... } },
    { "domain": "example.org", "status": "available" }
  ],
  "total":     3,
  "queryTime": 512
}

Response Schema

Cấu trúc đầy đủ của object WHOIS trả về.

Top-level fields

domain

string

Tên miền dạng ASCII/punycode (canonical key). Ví dụ: "xn--mnchen-3ya.de"

idnDomain

string | undefined

Dạng Unicode hiển thị của tên miền IDN. Chỉ có khi domain chứa nhãn quốc tế hóa (xn--). Ví dụ: "münchen.de". Bỏ qua với domain ASCII thuần.

tld

string

TLD của domain: "vn", "net", "com"…

status

"registered" | "available"

registered available

cached

boolean

Response từ cache hay live query

data

object | undefined

Chỉ có khi status = "registered"

backendsTried

array | undefined

Backends đã thử, chỉ có khi cached = false

data object (chỉ khi registered)

data.registrant.name

string | undefined

Tên chủ sở hữu. Chỉ có với .vn

data.registrar.name

string

Tên nhà đăng ký

data.nameservers

string[]

Danh sách nameserver

data.dates.created

ISO 8601 | null

Ngày tạo domain

data.dates.expiry

ISO 8601 | null

Ngày hết hạn

data.dates.updated

ISO 8601 | null

Ngày cập nhật gần nhất

data.domainStatus

string[]

EPP status codes: "clientTransferProhibited", "ok"…

data.dnssec

boolean

DNSSEC enabled

Mã lỗi

200 OK — Thành công Xử lý response bình thường

400 Bad Request — Domain không hợp lệ Validate format trước khi gọi

401 Unauthorized — Sai hoặc thiếu API key Kiểm tra header X-API-Key

429 Too Many Requests — Vượt rate limit Đợi theo header Retry-After

500 Internal Server Error Retry sau, báo cáo nếu lặp lại

503 Service Unavailable — Registry không phản hồi Exponential backoff retry

TLD hỗ trợ

1.260+ loại TLD bao gồm tất cả ccTLD, gTLD phổ biến và new gTLD.

✓ Tên miền .vn, .com.vn, .net.vn, .org.vn, .edu.vn, .gov.vn tra cứu trực tiếp qua VNNIC chính thức — dữ liệu chính xác, cập nhật nhanh nhất. Backend: vnnic-relay, latency ~145ms.

Code mẫu

WHOIS Lookup

javascript · Node.js 18+

const domain = 'bkns.vn';
const apiKey = 'YOUR_API_KEY';

const res = await fetch(
  `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
  { headers: { 'X-API-Key': apiKey } }
);

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

// Luôn check status trước khi access data.*
if (data.status === 'registered') {
  console.log('Nhà đăng ký:', data.data.registrar.name);
  console.log('Hết hạn:',     data.data.dates.expiry);
  console.log('Nameservers:',  data.data.nameservers.join(', '));
} else {
  console.log('Domain chưa được đăng ký.');
}

python

import requests

domain  = "bkns.vn"
api_key = "YOUR_API_KEY"

response = requests.get(
    "https://whois.bkns.vn/api/v1/whois",
    params={"domain": domain},
    headers={"X-API-Key": api_key},
    timeout=10,
)
response.raise_for_status()
data = response.json()

# Luôn check status trước khi access data
if data["status"] == "registered":
    print(f"Nhà đăng ký: {data['data']['registrar']['name']}")
    print(f"Hết hạn: {data['data']['dates']['expiry']}")
else:
    print("Domain chưa được đăng ký.")

php

<?php
$domain  = 'bkns.vn';
$apiKey  = 'YOUR_API_KEY';

$ch = curl_init('https://whois.bkns.vn/api/v1/whois?domain=' . urlencode($domain));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $apiKey],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

// Luôn check status trước khi access data
if ($data['status'] === 'registered') {
    echo "Nhà đăng ký: " . $data['data']['registrar']['name'] . "\n";
    echo "Hết hạn: "    . $data['data']['dates']['expiry']      . "\n";
} else {
    echo "Domain chưa được đăng ký.\n";
}

shell

curl -s \
  "https://whois.bkns.vn/api/v1/whois?domain=bkns.vn" \
  -H "X-API-Key: YOUR_API_KEY" \
  | python3 -m json.tool

Xử lý 429 — Retry với backoff

javascript

async function whoisWithRetry(domain, apiKey, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(
      `https://whois.bkns.vn/api/v1/whois?domain=${domain}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    if (res.status === 429) {
      const wait = Number(res.headers.get('Retry-After') ?? 5) * 1000;
      await new Promise(r => setTimeout(r, wait));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  }
}

Liên hệ

Cần hỗ trợ kỹ thuật hoặc muốn đăng ký API key Partner?

✉