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. Ví dụ: `bkns.vn`, `google.com`

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

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 đầy đủ

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?

✉