Python SDK — whatsapp-data-sdk

安装

pip install whatsapp-data-sdk

支持 Python 3.8-3.13。自带 py.typed 标记，可实现完整的类型检查器支持（mypy、pyright）。

快速入门

from whatsapp_data_sdk import WhatsAppDataClient

client = WhatsAppDataClient(api_key="YOUR_KEY")  # sent as x-rapidapi-key

profile = client.get_profile("59898297150")
print(profile.get("exists"), profile.get("about"), profile.get("profilePic"))

认证与传输

您的密钥始终通过 x-rapidapi-key 发送。选择请求的传输路径。

client = WhatsAppDataClient(api_key="RAPIDAPI_KEY", transport="rapidapi")

通过 base_url、cache_base_url、rapidapi_host、rapidapi_cache_host 覆盖 URL/主机。

缓存优先查找（节省成本）

check_cached() 首先读取廉价的缓存/仅数据库端点，只有在真正未命中时才会回退到付费的实时检查。

r1 = client.check_cached("59898297150")                  # cacheFirst (default)
print(r1["_source"])                                     # "cache" | "live"
r2 = client.check_cached("59898297150", mode="cacheOnly")  # never a live call
r3 = client.check_cached("59898297150", mode="live")       # always fresh

权威的缓存中不存在的 WhatsApp 记录会被计为一次命中（无需浪费时间进行实时重新检查）；只有真正的 NOT_IN_DATABASE 未命中才会传递到实时系统。

API 参考

每个方法都与市场端点 1:1 对应 - 与 npm SDK 的覆盖范围相同，采用 snake_case 命名法。

# Profile & pictures
client.get_profile(number, telegram=True, include_carrier=True)  # Get Profile Information
client.get_profile_no_picture(number)                            # (No profile pic)
pic = client.get_last_picture(number)                            # JPEG bytes -> pic.content, pic.to_data_uri()
client.get_device_count(number)                                  # Device count
client.get_osint_info(number)                                    # OSINT Info

# Breaches
client.get_phone_breaches(number, limit=50)                      # built-in (no external key)
client.get_phone_breaches_external(number, api_key="...")        # your checkleaked.cc key

# Search & database
client.search(country_code="UY", is_business=True, limit=20)     # Search
client.search_google_maps(latitude=-34.9, longitude=-56.16, radius=2000)  # Search in Google Maps
client.get_leaked_numbers_info()                                 # Leaked Numbers (500M) -> Drive link (MEGA tier)
client.download_entire_database()                                # Download the Entire DB -> Drive link (MEGA tier)

# Bulk
client.bulk_check(numbers)                                       # live (max 50)
client.bulk_check_db_basic(numbers)                              # DB basic (max 1000)
client.bulk_check_db_full(numbers)                                # DB full (max 1000)

# Telegram / carrier
client.get_telegram_profile("59898297150")                      # experimental
client.get_telegram_profile(["num1", "num2"])
client.carrier_lookup(number)                                    # Carrier Lookup
client.carrier_lookup_alt(number, page=2)                        # Carrier Lookup Alternative

“未找到”问题已解决——不会引发异常。

号码不在 WhatsApp 上属于正常结果，因此这些结果会得到解决（不会引发争议）：

p = client.get_profile("14155552671")
if not p.get("exists"):
    print("not on WhatsApp")

会引发以下错误：无效号码 (400)、身份验证 (401/403)、速率限制 (429)、超时、网络、5xx。

按请求选项

每种方法都接受超时（秒）设置并进行重试：

client.get_profile("59898297150", timeout=5, retries=0)

错误

所有失败都会引发 WhatsAppDataError 的子类。

from whatsapp_data_sdk import AuthError, RateLimitError, WhatsAppDataError

try:
    client.get_profile("59898297150")
except AuthError:
    ...  # 401/403
except RateLimitError as e:
    print(e.retry_after_ms)
except WhatsAppDataError as e:
    print(e.status, e.body)

POST 请求（bulk_check、bulk_check_db_*）不会自动重试，以避免重复花费配额。

电话号码格式

任何格式都可以——SDK 会自动进行规范化；辅助函数也会被导出：

from whatsapp_data_sdk import to_digits, to_e164
to_digits("+598 98 297 150")  # "59898297150"  (path & live endpoints)
to_e164("59898297150")        # "+59898297150" (bulk-DB endpoints require it)

有关的