一、引言

在当今瞬息万变的市场环境当中，时间就相当于金钱。现在很多的行业，例如，保险行业，还是以电销为主。在这过程中，就常常面临着大量的无效号码的困扰。例如，拨打大量的手机号码，其中却有很多的空号，停机，或者是无法接通的情况。不仅大大的浪费了宝贵的时间，而且极有可能错失了特别重要的商机，转换效率低下。手机空号检测 API 就能够帮助你快速的识别实号，避免无效通话，实现精准营销，获得更高的投资回报。

二、API 功能详解

根据顾客提供的手机号分类选出其中的空号、实号，风险号和沉默号，该产品直连运营商权威渠道。
空号：指的是根本不存在的号码，或者是该号码从未被激活过，或者是使用过。命中准确率为 100%，误杀率为 5%，出现误差的原因，可能停机的手机号恢复了使用。
实号：有效的，可以正常使用的手机号码。命中准确率为 100%，误差率 5%，出现误差的原因可能意外停机。
风险号：只可能存在问题的一些号码，例如，一些号码可能与诈骗或恶意活动相关联。
沉默号：号码虽然存在，但是长时间未被使用。虽然不是空号，但也可能无法联系到用户。API 通过检测该号码是否超过六个月未激活过空号和近三个月平均流量低于 30M 的用户来判断

空号检测 API 还可以和同平台探数 API 的手机在网状态查询接口同步使用，更加全面的号码筛选，提高号码的整体质量，最终提升营销和回访回报率。

三、Python 使用示例

请求方式
支持GET/POST请求方式，推荐使用GET进行简单查询。

返回格式
JSON 格式
请求参数说明

返回参数说明

状态码说明：

0：空号
1：实号（活跃）
2：停机
3：库无
4：沉默号（不常用）
5：风险号

Python调用示例代码

以下是一个完整的 Python 脚本示例，演示如何调用【实时空号检测API】：

import requests
import json

def check_phone_status(api_key, phone_number):
    """
    调用空号检测API，获取手机号状态
    :param api_key: API请求密钥
    :param phone_number: 待查询的手机号
    :return: 解析后的JSON响应数据
    """
    url = "https://api.tanshuapi.com/api/phone_invalid/v1/index"

    # 构造请求参数
    params = {
        'key': api_key,
        'phone': phone_number
    }

    try:
        # 发起GET请求
        response = requests.get(url, params=params)
        # 解析JSON响应
        result = response.json()

        if result['code'] == 1:
            data = result['data']
            print("查询成功！")
            print(f"手机号：{data['phone']}")
            print(f"归属地：{data['province']} - {data['city']}")
            print(f"运营商：{data['isp']}")
            print(f"区号：{data['areacode']}")
            print(f"邮政编码：{data['zipcode']}")
            print(f"状态码：{data['status']}")

            status_desc = {
                '0': '空号',
                '1': '实号（活跃）',
                '2': '停机',
                '3': '库无',
                '4': '沉默号（不常用）',
                '5': '风险号'
            }
            print(f"状态描述：{status_desc.get(data['status'], '未知状态')}")

        else:
            print(f"查询失败：{result['msg']}")

    except Exception as e:
        print(f"请求过程中发生错误：{e}")

# 示例调用
if __name__ == '__main__':
    api_key = 'your_api_key_here'         # 替换为你的API Key
    phone_number = '15878458784'          # 替换为你要查询的手机号

    check_phone_status(api_key, phone_number)

批量处理建议（可选）

def batch_check_phones(api_key, phone_list):
    for phone in phone_list:
        print(f"\n正在查询手机号：{phone}")
        check_phone_status(api_key, phone)

# 示例：从列表中批量查询
phones = ['15878458784', '13912345678', '18887654321']
batch_check_phones('your_api_key_here', phones)

常见错误码与排查建议
系统级错误码（10001 - 10008）

服务级错误码（207201 - 207202）

该 API 支持多行业的场景应用
电销或呼叫中心，帮助呼叫前清洗一下号码库使其专注有效客户。
短信营销：电销，教育等行业在群发促销时，能够提前过滤无效的号码

✅ 高准确率：直连运营商，非缓存库，确保数据实时更新。
✅ 支持高并发：适用于大规模号码批量处理。
✅ 多维度信息返回：包括归属地、运营商、状态等10+字段。
✅ 适用性强：广泛应用于短信营销、注册验证、CRM管理等多个行业。
✅ 搭配使用更高效：可与手机在网状态查询接口同步使用，全面掌握用户活跃度。