API xác thực và định dạng số điện thoại

Dữ liệu điện thoại toàn cầu

Một số điện thoại, đầu ra nhất quán

Chấp nhận số quốc gia, quốc tế và định dạng không đồng nhất, sau đó trả về định dạng chuẩn cùng dữ liệu xác thực cho 242 quốc gia và vùng lãnh thổ.

Đầu vào thô+1 212 867 5309

Đầu ra E.164+12128675309

Xác thựcisValid and isPossible

Định dạngQuốc gia, quốc tế và E.164

Phân loạiDi động, cố định, VoIP và loại khác

Vị tríVùng, mã vùng và địa điểm

Tham số đầu vào

Ngữ cảnh số và địa chỉ

Tham số	Yêu cầu	Mô tả
`number`	Bắt buộc	Số điện thoại ở định dạng quốc gia, quốc tế hoặc E.164.
`address`	Có điều kiện	Mã quốc gia ISO, tên quốc gia, thành phố hoặc vùng dùng để diễn giải số quốc gia.

Khi address trở thành bắt buộc

If number does not begin with + and an international calling code, provide context such as US, United States or New York.

USGermanyİstanbulNew YorkÉtats-Unis

GET

Xác thực bằng query string

Yêu cầu GET cơ bản

cURL

curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"

Mã hóa URL: Encode + as %2B and spaces as %20. Prefer your language’s URL/URLSearchParams utilities over manual string construction.

POST

Xác thực Bearer

Yêu cầu POST phía máy chủ

Gửi số và address tùy chọn dưới dạng JSON, với API key trong Authorization header.

cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Kiểu: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number":"+12128675309","address":"US"}'

JavaScript

const response = await fetch("https://api.genderapi.io/api/phone", {
  method: "POST", headers: { "Content-Kiểu": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
  body: JSON.stringify({ number: "+12128675309", address: "United States" })
});

Phản hồi API

Xác thực, formatting and metadata

JSON

{
  "status": true, "remaining_credits": 15709, "expires": 0, "duration": "18ms",
  "regionCode": "US", "countryCode": 1, "country": "United States",
  "national": "(212) 867-5309", "international": "+1 212-867-5309", "e164": "+12128675309",
  "isValid": true, "isPossible": true, "numberKiểu": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309", "rawInput": "+1 212 867 5309",
  "isGeographical": true, "areaCode": "212", "location": "New York City (Manhattan)"
}

Các trường phản hồi

Trường	Kiểu	Mô tả
`status`	boolean	Cho biết yêu cầu có hoàn tất thành công hay không.
`remaining_credits`	integer	Số credit còn lại sau yêu cầu.
`expires`	integer	Thời điểm hết hạn credit dưới dạng UNIX timestamp.
`duration`	string	Thời gian xử lý trên máy chủ.
`regionCode`	string	Mã vùng ISO 3166-1 alpha-2 được phát hiện.
`countryCode`	integer	Mã gọi quốc tế.
`country`	string	Tên quốc gia dễ đọc.
`national`	string	Số được định dạng để dùng trong nước.
`international`	string	Số được định dạng để hiển thị quốc tế.
`e164`	string	Biểu diễn E.164 chuẩn.
`isValid`	boolean	Cho biết số có đáp ứng quy tắc xác thực khu vực hay không.
`isPossible`	boolean	Cho biết số có thể tồn tại dựa trên cấu trúc hay không.
`numberKiểu`	string	Loại số được phát hiện.
`nationalSignificantNumber`	string	Số quốc gia không gồm mã gọi quốc tế.
`rawInput`	string	Số gốc được gửi trong yêu cầu.
`isGeographical`	boolean	Cho biết số có liên kết với khu vực địa lý hay không.
`areaCode`	string	Mã vùng được phát hiện.
`location`	string	Địa điểm liên kết với mã vùng.

Phân loại reference

Các giá trị loại số

FIXED_LINE

Điện thoại cố định gắn với một vị trí địa lý.

MOBILE

Số điện thoại di động.

FIXED_LINE_OR_MOBILE

Kế hoạch đánh số không phân biệt cố định và di động.

TOLL_FREE

Số miễn cước do bên nhận trả phí.

PREMIUM_RATE

Số dịch vụ tính cước cao.

SHARED_COST

Chi phí cuộc gọi được chia sẻ giữa người gọi và người nhận.

VOIP

Số điện thoại qua giao thức IP.

PERSONAL_NUMBER

Số cá nhân có thể chuyển tiếp đến đường dây khác.

PAGER

Số máy nhắn tin.

UAN

Số truy cập chung dùng làm liên hệ doanh nghiệp.

VOICEMAIL

Số truy cập thư thoại chuyên dụng.

UNKNOWN

Không thể xác định loại số.

Câu hỏi thường gặp

Câu hỏi về Phone API

API xác thực số điện thoại làm gì?

API xác thực và chuẩn hóa số điện thoại, trả về định dạng quốc gia, quốc tế và E.164, đồng thời nhận diện vùng, loại số và dữ liệu địa lý khi có.

isValid và isPossible khác nhau thế nào?

isValid kiểm tra số theo quy tắc đánh số khu vực; isPossible cho biết cấu trúc có thể là một số điện thoại dù chưa xác nhận được tính hợp lệ.

Khi nào cần address?

Cung cấp address khi số không bắt đầu bằng dấu cộng và mã gọi quốc tế. Giá trị có thể là mã quốc gia ISO, tên quốc gia, thành phố hoặc vùng.

Nên gửi ký tự đặc biệt như thế nào?

Mã hóa URL cho khoảng trắng, dấu cộng và ký tự đặc biệt trong tham số GET. Phần thân JSON POST được HTTP client mã hóa.

Tài liệu tiếp theo

Theo dõi mức sử dụng và hạn mức

Mức sử dụng và hạn mứcTìm hiểu credit và giới hạn →Thư viện clientCài đặt gói xác thực số điện thoại →