Python SDK
타입이 지정된 리소스, 커서 기반 페이지네이션, 자동 재시도, 이름이 지정된 오류를 제공하는 Listings API 공식 Python 클라이언트입니다.
listingsapi 패키지는 Listings API의 공식 Python 클라이언트입니다. REST 계층을 감싸 타입이 지정된 리소스 클래스, 커서 기반 페이지네이션, 일시적 오류에 대한 자동 재시도, 플랫폼이 HTTP 200으로 반환하는 오류 페이로드를 포함한 모든 실패 유형에 대해 이름이 지정된 예외를 제공합니다.
설치
pip install listingsapiPython 3.9 이상이 필요합니다. 유일한 런타임 의존성은 requests입니다.
인증
import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")Listings API 개발자 대시보드의 API Keys → New key에서 API 키를 발급받습니다.
클라이언트는 3개의 선택적 키워드 인수를 받습니다.
자세한 내용은 설정을 참조합니다.
간단한 예제
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page: print(loc.name, loc.city) print(f"has_more: {page.has_more}")리소스
모든 리소스는 클라이언트의 속성입니다.
클라이언트 자체에 4개의 보조 메서드가 있습니다.
client.plan_sites() # directories included in your planclient.subcategories() # business categories (IDs for locations.add)client.countries() # supported countries and states (ISO codes)client.subscriptions() # active subscriptions for the account페이지네이션
목록을 반환하는 메서드는 커서 기반 페이지네이션을 사용합니다. 페이지네이션을 지원하는 모든 메서드는 반복 가능하며 .has_more, .next_page(), .auto_paging_iter(), .total를 제공하는 SyncPage을 반환합니다.
# Fetch one pagepage = client.locations.list(first=25)for loc in page: print(loc.name) # Check if more pages existif page.has_more: next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter(): print(loc.name)응답 객체
모든 메서드는 APIObject(속성 및 dict 방식으로 접근 가능) 또는 SyncPage(반복 가능, 페이지네이션 지원)을 반환합니다. APIObject는 .get()와 .to_dict()도 지원합니다.
loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()오류 처리
모든 SDK 오류는 listingsapi.ListingsAPIError을 상속합니다. API 실패 시 APIError 또는 그 하위 클래스인 AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError(.retry_after 포함), InternalServerError 중 하나가 발생합니다. 네트워크 실패 시 APIConnectionError가 발생합니다.
APIError에는 status_code, code(첫 번째 플랫폼 오류 코드, e.g. SY10005), errors(모든 항목이 {"code", "message", "context"} dict로 정규화됨), response_body이 포함됩니다.
플랫폼은 일부 실패를 HTTP 200 본문에 담아 보고합니다. 여기에는 최상위 errors[] 페이로드(유효하지 않은 토큰은 SY90005로 반환됨)와 success=false가 포함된 쓰기 응답이 해당합니다. SDK는 이러한 경우에도 예외를 발생시키므로 success 플래그를 직접 검사할 필요가 없습니다.
import listingsapi client = listingsapi.ListingsAPI() try: client.locations.retrieve(999999)except listingsapi.NotFoundError: print("No such location")except listingsapi.RateLimitError as e: print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e: print(e.status_code, e.code) for err in e.errors: print(err["code"], err["message"])전체 예외 계층 구조는 오류 처리를 참조합니다.