파이썬 SDK — whatsapp-data-sdk

설치하다

pip install whatsapp-data-sdk

Python 3.8~3.13 버전을 지원합니다. mypy, pyright와 같은 타입 검사 도구를 완벽하게 지원하기 위해 py.typed 마커가 포함되어 있습니다.

빠른 시작

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() 함수는 먼저 저렴한 캐시/DB 전용 엔드포인트를 읽고, 캐시가 실제로 누락된 경우에만 유료 실시간 확인으로 전환합니다.

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)

관련된