电话号码验证与格式化 API

电话号码验证 API 支持 242 个国家和地区。

电话号码验证与格式化 API 让你可以轻松处理用户输入的各种格式的电话号码。无论输入是 1(212)-867-53-09、+1 212 8675309、001-212.867.5309 还是仅仅 2128675309，我们的 API 都能智能识别结构并返回标准化的版本。

此工具会自动将输入号码转换为E.164 格式，这是国际通用的电话号码标准格式。例如，+1 212 867 5309 会被转换为 +12128675309，非常适用于国际呼叫系统和各种集成应用。

除了格式化之外，API 还提供了详细的电话号码有效性验证功能。它会检查号码是否 isValid: true（即根据国家编号规则是有效号码）。同时还有 isPossible: true 检查，这表示该号码在理论上可能存在（即使当前未分配）。这个特性对于保存或处理前的预验证非常有用。

numberType 参数可帮助识别号码类型是手机、座机还是 VoIP。在只允许手机号接收短信验证，或仅允许座机用于办公联系等场景中非常实用。

支持区号识别，API 还能检测号码的地理归属。例如，区号为 212 的号码会自动映射到纽约市（曼哈顿）。此功能非常适合需要按地区划分或分析的应用。

每个号码还包含了详细的国家级元数据，如 ISO 区域代码（例如 US）和国家数字代码（例如 1），让你的应用可以根据地区进行逻辑判断或不同的展示格式。

✅ API 响应示例

示例 JSON 响应： 

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country":"Unites 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)"
}
正在加载...
您的额度已用完。注册即可获得200 次免费额度。
免费注册

亲自试用电话验证 API

基本用法

将电话号码发送到以下端点： 

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

您可以通过此链接每日免费获得 200 次 API 调用额度。


地址参数 address

API 还支持一个可选的 address 参数。当电话号码没有国际区号时，这一参数非常有用。它帮助系统检测目标地区并正确解析号码。例如，如果输入号码是 2128675309，未指定国家区号，通过设置 address=US、address=United States 或 address=New York 等，可以让 API 判断号码属于美国。

address 参数支持多种格式，包括：

  • ISO 3166-1 alpha-2 代码，如 US、DE、TR
  • 国家名称，如 Germany、Turkey、America
  • 城市或地区名称，如 Berlin、Istanbul、New York

虽然 address 是可选参数，但如果电话号码不是以加号和国际区号开头（例如 +1、+44、+90），则该参数变为必填。否则，API 可能无法正确解析国家本地号码格式。

地址参数示例： 

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

响应字段

字段 类型 说明
status Boolean 如果请求成功，则为 true。
remaining_credits Integer 本次请求后剩余的 API 配额数量。
expires Integer (timestamp) 配额到期时间，UNIX 时间戳（秒）。
duration String 处理请求所花费的时间（如 308ms）。
regionCode String 检测到的国家的 ISO 3166-1 alpha-2 区域代码（如 US）。
countryCode Integer 该国家/地区的国际区号（如美国为 1）。
country String 完整的国家名称（如：United States）。
national String 本地格式化后的电话号码（如 (212) 867–5309）。
international String 国际格式化后的电话号码（如 +1 212–867–5309）。
e164 String E.164 格式的电话号码（如 +12128675309）。
isValid Boolean 如果号码符合本地区号规则，则为 true。
isPossible Boolean 如果号码结构有效且理论上可能存在（即使未分配），则为 true。
numberType Enum[String] 电话号码类型。可能的取值：FIXED_LINE、MOBILE、FIXED_LINE_OR_MOBILE 等。
nationalSignificantNumber String 不包含国家区号的完整本地号码（如 2128675309）。
rawInput String API 请求时提供的原始电话号码。
isGeographical Boolean 如果号码可关联至地理区域（如座机），则为 true。
areaCode String 号码的区号部分（如 212）。
location String 与区号关联的地理位置（如 New York City (Manhattan)）。

号码类型取值

类型 说明
FIXED_LINE 绑定到某一地理区域的标准座机号码。
MOBILE 可以接听电话和短信的手机号码。
FIXED_LINE_OR_MOBILE 号码可能是座机也可能是手机，编号规则无法区分。
TOLL_FREE 免费电话号码，由接收方支付费用，例如美国的 800 开头号码。
PREMIUM_RATE 付费服务号码，通常费用较高，常用于娱乐或信息服务。
SHARED_COST 费用由主叫和被叫共同分担的号码。
VOIP 互联网语音（VoIP）号码，如 Skype 或 Google Voice。
PERSONAL_NUMBER 可被转接到用户选择的任意电话号码的个人号码。
PAGER 寻呼机号码，用于文本通知（现已基本淘汰）。
UAN 统一接入号码，企业用于统一联络点。
VOICEMAIL 专用于语音信箱服务的号码。
UNKNOWN 无法确定号码类型。

⚠️ 警告： 如果您的输入值包含空格或特殊字符（例如电话号码中的 + 符号或国家名称中的空格）， 在发送 GET 请求之前请务必对其进行 URL 编码。否则，您的请求可能会失败或参数可能被误解。

❌ 错误示例： 
curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"
✅ 正确用法（URL 编码）： 
curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"
您还可以使用编程语言中的 URL 编码函数，在发送请求前对参数进行编码。

通过 POST 请求使用电话验证 API

您可以使用 POST 方法验证美国的电话号码。 只需提供 E.164、本地或国际格式的电话号码以及国家/地区（address）。 API 密钥需以 Bearer Token 方式发送。


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"}'

PHP cURL 示例

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

JavaScript fetch 示例

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"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Python requests 示例

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

客户端库

为了让集成更加简单，我们为不同的编程语言提供了一系列官方和社区支持的客户端库。 通过这些库，您可以直接与 GenderAPI 各个端点（如电话号码验证 API）进行交互，而无需手动处理 HTTP 请求或 JSON 解析。 只需选择适合您环境的库，安装后即可快速开始调用 API。

您可以在以下页面找到可用的客户端库及安装说明：
https://www.genderapi.io/zh/docs-client-libraries

常见问题（FAQ）


1. 什么是电话号码验证与格式化 API？

电话号码验证与格式化 API 是一个可以对全球电话号码进行验证、格式化和分析的工具。它能够将号码转换为标准的 E.164 格式，并判断区域、类型（手机/座机）、有效性等元数据。

2. 电话号码验证功能的用途是什么？

它用于检查号码是否合法，将其格式化为国际通用格式，识别号码类型（如手机、VOIP），检测基于地区的元数据，并确保 CRM、营销工具或用户注册时输入的电话号码标准且规范。

3. 支持多少个国家？

该 API 支持来自 全球 242 个国家和地区 的电话号码，确保所有国际或本地化应用都能覆盖。

4. 支持哪些号码格式？

API 支持多种格式输入，如本地格式、国际格式或 E.164 格式。系统会自动检测并标准化为正确格式。

5. 如果我省略了国家或地址参数会怎样？

如果号码不是以 “+” 开头且未提供国家/地址参数，API 可能无法正确解析该号码。建议包含 address 参数（如 US、United States 或 New York）。

6. API 能识别号码类型吗？

可以。API 会返回 numberType 字段，指示号码是 MOBILE、FIXED_LINE、VOIP 等类型。

7. isValid 和 isPossible 有什么区别？

isValid 表示该号码已被正式分配且符合地区规则；isPossible 检查该号码结构在理论上是否可能存在，即使当前未分配。

8. API 返回什么样的响应？

成功响应包括状态、各种格式的号码（本地、国际、E.164）、区域数据、号码类型、配额使用情况等。完整示例请参考 API 响应示例部分。

9. 我该如何发送 API 密钥？

对于 GET 请求，将密钥作为 ?key=YOUR_API_KEY 添加。对于 POST 请求，请在请求头中以 Bearer Token 方式发送，如：
"Authorization: Bearer YOUR_API_KEY"。

10. 如果我看到 status: false 的响应怎么办？

这表示请求失败。message 字段会包含详细的错误原因，如参数缺失、电话号码无效或额度不足等。

11. 输入中允许使用特殊字符或空格吗？

允许，但在 GET 请求中必须进行 URL 编码。例如，空格应使用 %20 代替。请参见上方警告部分了解正确用法。

12. 地址参数可以用不同格式或语言吗？

可以。除了 ISO 3166-1 alpha-2 代码（如 US、DE、TR），address 参数也支持完整的国家名称或城市名称——甚至可以使用不同的语言。API 内置 AI 能智能检测和解析对应国家或地区。例如： 

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

上述所有输入，API 都能正确映射到相应国家或地区，无需担心解析问题。