Python实战：对接天远数据手机号码归属地API，实现精准用户分群与本地化运营

数字化运营中的精准定位与风控基石

在当今的移动互联网生态中，无论是电商平台的精准营销，还是金融信贷的反欺诈风控，"用户在哪里"始终是一个核心命题。盲目的短信群发不仅转化率低，更可能因为跨区营销遭到投诉；而在金融场景下，手机号归属地与IP地址、收货地址的非一致性往往是身份冒用的高危信号。

传统的本地号码库维护成本高、更新滞后，已无法满足实时业务需求。天远API 提供的手机号码归属地核验服务，正是解决这一痛点的标准化方案。它通过轻量化的接口调用，为企业提供毫秒级的"手机号→地域/运营商"映射能力，帮助开发者构建数据驱动的业务逻辑，确保每一条营销信息和风控策略都能精准触达目标。

Python 接口集成实战指南

本节演示如何通过 Python 快速对接归属地查询接口。由于该接口采用了高安全性的 AES-128 加密机制，我们在示例代码中封装了必要的异常处理和超时逻辑，确保生产环境的稳定性。

前置准备

• API Endpoint : https://api.tianyuanapi.com/api/v1/YYSY9E4A
• Access-Id: 请在控制台获取
• Access Key: 用于 AES 加密的 16 进制密钥

核心代码实现

Python

import requests
import json
import base64
import time
# 实际开发中请使用 pycryptodome 库进行 AES 操作
# from Crypto.Cipher import AES

def query_mobile_attribution(mobile_no, access_id, access_key):
    """
    调用天远手机号归属地API
    :param mobile_no: 目标手机号
    :param access_id: 账户ID
    :param access_key: 16进制密钥
    """
    url = "https://api.tianyuanapi.com/api/v1/YYSY9E4A"
    
    # 1. 构建基础参数并添加时间戳防止重放攻击
    timestamp = int(time.time() * 1000)
    request_url = f"{url}?t={timestamp}"
    
    payload = {
        "mobile_no": mobile_no
    }
    
    try:
        # 2. 数据加密处理 (AES-CBC 模式)
        # 注意：此处为逻辑示意。实际开发需实现 AES-128-CBC 加密，
        # 生成随机 16 字节 IV，填充方式为 PKCS7。
        # 最终数据结构为: Base64(IV + Ciphertext)
        encrypted_data = _encrypt_data(json.dumps(payload), access_key) 
        
        headers = {
            "Access-Id": access_id,
            "Content-Type": "application/json"
        }
        
        body = {
            "data": encrypted_data
        }

        # 3. 发送请求，设置超时时间防止阻塞
        response = requests.post(request_url, json=body, headers=headers, timeout=5)
        
        # 4. 响应解析
        if response.status_code == 200:
            res_json = response.json()
            
            # 业务层面的状态码判断
            if res_json.get("code") == 0:
                # 解密响应数据：提取前16字节IV -> AES解密 -> 去除PKCS7填充
                decrypted_content = _decrypt_data(res_json.get("data"), access_key)
                return json.loads(decrypted_content)
            else:
                print(f"业务异常: Code {res_json.get('code')}, Message: {res_json.get('message')}")
                return None
        else:
            print(f"HTTP请求失败: {response.status_code}")
            return None
            
    except requests.exceptions.Timeout:
        print("请求超时，请检查网络或增加超时时间")
    except requests.exceptions.RequestException as e:
        print(f"请求发生错误: {e}")
    except Exception as e:
        print(f"系统内部错误: {e}")

def _encrypt_data(plain_text, key):
    """
    [占位函数] AES-128-CBC 加密逻辑
    开发者需实现：IV随机生成 + PKCS7填充 + AES加密 + Base64编码
    详情参考官方文档加密机制章节
    """
    return "base64_encrypted_string_placeholder"

def _decrypt_data(cipher_text, key):
    """
    [占位函数] AES-128-CBC 解密逻辑
    开发者需实现：Base64解码 -> 提取IV -> AES解密 -> 去除填充
    """
    return '{"provinceName": "安徽", "cityName": "淮南", "channel": "中国电信"}'

# 调用示例
if __name__ == "__main__":
    result = query_mobile_attribution("1995549xxxx", "YOUR_ACCESS_ID", "YOUR_ACCESS_KEY")
    if result:
        print(f"归属地: {result['provinceName']}-{result['cityName']}")

Curl 测试命令

如果您希望在终端快速调试，可以使用以下 curl 命令（注意 data 需替换为实际加密后的 Base64 字符串）：

Bash

curl -X POST "https://api.tianyuanapi.com/api/v1/YYSY9E4A?t=1735689600000" \
     -H "Access-Id: YOUR_ACCESS_ID" \
     -H "Content-Type: application/json" \
     -d '{"data": "YOUR_ENCRYPTED_BASE64_STRING"}'

数据结构深度解析

天远API 的响应设计非常扁平化，解密后的 JSON 数据直接包含了核心字段，没有深层嵌套，极大地简化了 ETL（数据清洗）的工作量。

以下是核心返回字段的详细解析及开发者注意事项：

字段名	类型	描述	开发者注意 (Developer Notes)
provinceName	String	省份	如"安徽"。在做数据落库时，建议建立标准化的省份映射表，以兼容不同数据源的省份别名（如"安徽省" vs "安徽"）。
cityName	String	城市	如"淮南"。可用于本地化服务推送或物流时效预估。
channel	String	运营商	如"中国电信"。关键字段。在短信通道路由选择时，根据此字段分流至特定运营商通道，可显著提升短信到达率并降低成本。
areaCode	String	区号	如"0554"。可辅助用于固定电话清洗或呼叫中心路由策略。
postCode	String	邮编	如"232000"。电商场景下可用于辅助用户快速填写地址信息。

状态码处理指南：

除了标准的 0 (业务成功) 外，开发者应重点关注 1002 (参数解密失败) 和 1007 (余额不足)。前者通常意味着 AES 密钥或 IV 处理逻辑有误，后者则需要建立余额监控预警机制。

挖掘 API 背后的业务价值

除了基础的归属地查询，开发者可以结合业务场景挖掘数据的深层价值：

1. 构建"人-地"一致性风控模型

   在金融信贷或高价值电商交易中，可以将 API 返回的 provinceName/cityName 与用户当前的 GPS 定位、IP 地址归属地以及收货地址进行交叉比对。如果手机号归属地为 A 地，但高频交易发生在 B 地且 IP 指向 C 地，这往往是账号被盗或欺诈团伙操作的强信号。

2. 存量用户分层清洗

   对于拥有海量历史用户数据的企业，可以通过该 API 对存量手机号进行一次性清洗。分析用户的地域分布热力图，识别核心市场区域。例如，发现某地区用户密度极高但活跃度低，可针对该地区策划专属的线下活动或本地化促销，激活沉睡用户。

3. 智能通信路由优化

   呼叫中心或短信平台可利用 channel (运营商) 字段实现智能路由。在发起外呼或发送验证码前，预先判断运营商归属，自动切换至该运营商的专用线路，不仅能提升接通率和到达率，还能规避跨网结算带来的额外成本。

最佳实践与建议

集成天远数据的手机号归属地 API 是提升业务数据精细度的重要一步。为了确保系统的高可用性和经济性，我们建议：

• 实施缓存策略：手机号码的归属地属性相对静态，不经常变更。建议在本地数据库或 Redis 中缓存查询结果（例如缓存 3-6 个月），避免对同一号码重复调用接口，从而节省费用。
• 安全合规：由于涉及用户隐私数据，务必利用好接口提供的 Access-Id 鉴权和 AES 加密机制，确保数据在传输过程中的绝对安全。