全球电话号码数据
一个号码，多种统一格式
提交国内、国际或不规则格式的号码，即可获得适用于 242 个国家和地区的标准化格式与验证元数据。
原始输入
→+1 212 867 5309E.164 输出
+12128675309验证
isValid 与 isPossible格式化国内、国际与 E.164
分类移动电话、固定电话、VoIP 等
位置地区、地区号与地点
输入参数
号码与地址信息
| 参数 | 要求 | 说明 |
|---|---|---|
number | 必填 | 采用国内、国际或 E.164 格式的电话号码。 |
address | 条件必填 | 用于解析国内号码的 ISO 国家代码、国家名称、城市或地区。 |
何时必须提供 address
如果 number 不是以 + 和国际电话区号开头，请提供 CN、China 或 Shanghai 等地区信息。
CNChinaShanghaiBeijingSingaporeGET
通过查询字符串验证身份
基础 GET 请求
cURL
curl "https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=%2B12128675309&address=US"URL 编码：将
+ 编码为 %2B，将空格编码为 %20。请优先使用编程语言提供的 URL/URLSearchParams 工具，不要手动拼接字符串。POST
Bearer 身份验证
服务端 POST 请求
以 JSON 发送号码和可选的 address，并在 Authorization 请求头中传入 API 密钥。
cURL
curl -X POST "https://api.genderapi.io/api/phone" \
-H "Content-Type: 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-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
body: JSON.stringify({ number: "+12128675309", address: "United States" })
});API 响应
验证、格式化与元数据
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, "numberType": "FIXED_LINE_OR_MOBILE",
"nationalSignificantNumber": "2128675309", "rawInput": "+1 212 867 5309",
"isGeographical": true, "areaCode": "212", "location": "New York City (Manhattan)"
}响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
status | boolean | 请求是否成功完成。 |
remaining_credits | integer | 请求完成后的剩余额度。 |
expires | integer | 额度到期时间，采用 UNIX 时间戳。 |
duration | string | 服务器处理时间。 |
regionCode | string | 检测到的 ISO 3166-1 alpha-2 地区代码。 |
countryCode | integer | 国际电话区号。 |
country | string | 便于阅读的国家/地区名称。 |
national | string | 按国内使用方式格式化的号码。 |
international | string | 按国际显示方式格式化的号码。 |
e164 | string | 规范的 E.164 格式。 |
isValid | boolean | 号码是否符合所在地区的验证规则。 |
isPossible | boolean | 根据号码结构判断其是否可能存在。 |
numberType | string | 检测到的号码类型。 |
nationalSignificantNumber | string | 不含国家电话区号的国内号码。 |
rawInput | string | 请求中提交的原始号码。 |
isGeographical | boolean | 号码是否可以关联到地理区域。 |
areaCode | string | 检测到的地区号部分。 |
location | string | 与地区号关联的位置。 |
类型参考
号码类型值
FIXED_LINE与地理位置关联的固定电话。
MOBILE移动电话号码。
FIXED_LINE_OR_MOBILE号码规划无法区分固定电话和移动电话。
TOLL_FREE由接听方付费的免费电话号码。
PREMIUM_RATE高资费服务号码。
SHARED_COST通话费用由主叫方和接听方共同承担。
VOIP基于 IP 语音的电话号码。
PERSONAL_NUMBER可转接至其他线路的个人号码。
PAGER寻呼机通知号码。
UAN企业共享联系使用的通用接入号码。
VOICEMAIL专用语音信箱接入号码。
UNKNOWN无法确定号码类型。
常见问题
电话号码 API 常见问题
电话号码验证 API 有什么作用？
它会验证并标准化电话号码，返回国内、国际和 E.164 格式，并在可用时识别地区、号码类型和地理元数据。
isValid 与 isPossible 有什么区别？
isValid 按地区号码规则验证号码；isPossible 表示其结构可能构成电话号码，即使尚不能确认其有效性。
什么时候必须提供 address？
当号码不是以加号和国际电话区号开头时，请提供 address。其值可以是 ISO 国家代码、国家名称、城市或地区。
如何发送特殊字符？
在 GET 查询参数中对空格、加号和其他特殊字符进行 URL 编码。POST 的 JSON 请求体由 HTTP 客户端编码。
下一篇参考