CheckPhone系统API接口文档
一、前言
CheckPhone 系统提供了号码检测服务，可以快速识别出号码类型，国家，运营商，地理位置等信息。系统支持单条号码实时检测、批量号码检测。
二、请求信息
鉴权：请求需要在请求header或者url中携带token参数，是对应账户的api_key。
三、接口列表
1. 单条号码检测
请求地址：/api/v1/check/single
请求方法：GET
| 参数 | 说明 |
|---|---|
| phone | 要检测的号码 |
请求示例
curl 'https://api.checkphone.cc/api/v1/check/single?phone=6857599999&token=xxxxxx'响应示例
{
"code": 200,
"message": "成功",
"trace_id": "0195d134-c338-71f6-a31b-c8ff9c51b230",
"data": {
"phone_valid": true,
"phone_type": "MOBILE",
"country": "Samoa",
"country_prefix": 685,
"country_code": "WS",
"carrier": "Bluesky",
"e164_number": "+6857599999",
"local_number": "75 99999",
"international_number": "+685 75 99999",
"geo_location": "Samoa",
"time_zone": "Pacific/Apia"
}
}响应示例说明:
| 响应参数 | 类型 | 描述 |
|---|---|---|
| code | number | 请求响应状态码，参考状态码表 |
| message | string | 请求响应信息 |
| trace_id | string | 响应编号，对应系统检测ID |
| data | object | 检测响应数据 |
| -- phone_valid | bool | 号码有效性 |
| -- phone_type | string | 号码类型，参考号码类型表 |
| -- country | string | 号码归属国家/地区名称 |
| -- country_prefix | number | 号码归属国家区号 |
| -- country_code | string | 号码归属国家代码 |
| -- carrier | string | 号码归属运营商 |
| -- e164_number | string | 号码e164规划格式 |
| -- local_number | string | 号码本地化格式 |
| -- international_number | string | 号码国际化格式 |
| -- geo_location | string | 号码所在地理位置 |
| -- time_zone | string | 号码所在时区 |
2. 批量号码检测
请求地址: /api/v1/check/batch
请求方法: POST
请求body:
| 请求参数 | 说明 |
|---|---|
| file | txt格式，号码数据文件，一行一个号码(带区号) |
请求示范
curl 'https://api.checkphone.cc/api/v1/check/batch' \
--header 'token: xxxxx' \
--form 'file=@"/tmp/tw100.txt"'响应示例:
{
"code": 200,
"message": "成功",
"trace_id": "0195d16c-2797-7254-84a2-92af5b237d4f",
"data": {
"before_count": 131,
"after_count": 100
}
}响应示例说明:
| 响应参数 | 类型 | 描述 |
|---|---|---|
| code | number | 请求响应状态码，参考状态码表 |
| message | string | 请求响应信息 |
| trace_id | string | 响应编号，对应系统检测任务ID |
| data | array | 检测响应数据 |
| -- before_count | number | 去重前数量 |
| -- after_count | Number | 去重后数量 |
3. 获取批量检测任务进度
请求地址: /api/v1/check/progress/:trace_id
请求方法: GET
请求参数:
| 请求参数 | 说明 |
|---|---|
| trace_id | 检测任务trace_id |
响应示例:
{
"code": 200,
"message": "成功",
"data": {
"after_count": 2000,
"status": "finished",
"start_time": 1742975281,
"end_time": 1742975281,
"progress": 2000
}
}响应示例说明:
| 响应参数 | 类型 | 描述 |
|---|---|---|
| code | number | 请求响应状态码，参考状态码表 |
| message | string | 请求响应信息 |
| data | object | 响应数据 |
| -- after_count | number | 检测号码数量 |
| -- status | string | 检测任务状态，参考任务状态表 |
| -- start_time | number | 任务开始时间，秒时间戳 |
| -- end_time | number | 任务结束时间，秒时间戳 |
| -- progress | number | 检测进度 |
4. 下载已完成任务
请求地址: /api/v1/check/download/:trace_id
请求方法: GET
请求参数:
| 请求参数 | 说明 |
|---|---|
| trace_id | 检测任务trace_id |
响应示例:
"号码","是否有效","类型","国家/地区","国家区号","国家代码","运营商","e164格式","本地格式","国际格式","地理位置","时区"
"886911057269","1","MOBILE","Taiwan","886","TW","Chunghwa Telecom","+886911057269","0911 057 269","+886 911 057 269","Taiwan","Asia/Taipei"
...四、参考
1. 响应码列表
| 响应码 | 说明 |
|---|---|
| 200 | 成功 |
| 401 | 未授权 |
| 402 | 剩余次数不足，需要购买订阅 |
| 403 | 无权限访问 |
| 404 | 请求接口不存在 |
| 405 | 请求方法错误 |
2. 任务状态表
| 任务状态 | 说明 |
|---|---|
| pending | 等待执行 |
| running | 执行中 |
| finished | 已完成 |
| failed | 任务失败 |