Listings APIListings API
로그인

설정

Listings API Python 클라이언트의 API 키, 기본 URL, 타임아웃, 재시도 및 로깅을 설정합니다.

생성자 시그니처

Python
listingsapi.ListingsAPI(    api_key: str | None = None,    *,    base_url: str | None = None,    timeout: float = 240.0,    max_retries: int = 2,)

모든 인수는 선택 사항입니다. api_key을 생략하면 클라이언트는 환경에서 LISTINGSAPI_KEY을 읽으며, 둘 다 설정되지 않은 경우 생성 시 AuthenticationError 예외를 발생시킵니다.

옵션

옵션타입기본값설명
api_keystr | NoneNoneAPI 키입니다. 지정하지 않으면 LISTINGSAPI_KEY 환경 변수를 사용합니다.
base_urlstr | Nonehttps://listingsapi.comAPI 오리진입니다. 끝에 있는 슬래시는 자동으로 제거됩니다.
timeoutfloat240.0요청별 제한 시간이며 단위는 초입니다(각 HTTP 요청에 개별적으로 적용됩니다).
max_retriesint2429 및 5xx 응답 시 자동으로 재시도합니다. 비활성화하려면 0로 설정합니다.

API 키

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi # From environment (recommended)client = listingsapi.ListingsAPI() # Explicit keyclient = listingsapi.ListingsAPI(api_key="your-api-key")

제한 시간

기본값은 240.0초입니다. 실행 시간이 짧은 스크립트나 대화형 사용에는 더 짧은 값을 설정할 수 있습니다:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

제한 시간은 각 HTTP 요청에 개별적으로 적용됩니다. 일괄 페이지네이션 호출(auto_paging_iter)에서도 요청별 제한 시간이 독립적으로 적용됩니다.

재시도

SDK는 requests 세션에 urllib3 Retry 어댑터를 연결하여 429, 500, 502, 503, 504 응답 시 자동으로 재시도하지만, GET, HEAD, OPTIONS과 같은 안전한 메서드에만 적용됩니다. 쓰기 요청(POST, DELETE)은 정확히 1번 전송되며, 실패하면 즉시 예외를 발생시킵니다. 기본 재시도 횟수는 2회이며, 지수 백오프 계수는 0.5초입니다. Retry-After 헤더를 따르므로, 대기 시간을 지정하는 429의 경우 정확히 해당 시간이 지난 후 재시도합니다.

v4 API는 Idempotency-Key을 지원하지 않고 반복된 쓰기를 감지하지 않으므로, 제한 시간을 초과하거나 5xx을 반환한 쓰기도 이미 커밋되었을 수 있습니다. 확인 없이 재시도하면 사업장, 게시물 또는 리뷰 답글이 중복 생성됩니다. 쓰기를 반복하기 전에 직접 관리하는 키로 레코드를 다시 조회합니다.

Python
# More aggressive retry for long-running batch jobsclient = listingsapi.ListingsAPI(max_retries=5) # Disable retries entirely (e.g. when you want fast failures)client = listingsapi.ListingsAPI(max_retries=0)

모든 재시도 후에도 429이 발생하면 RateLimitError 예외가 발생합니다. 수동 백오프 구현 방법은 오류 처리를 참조합니다.

기본 URL 재정의

스테이징 환경이나 내부 프록시에 유용합니다:

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

끝에 있는 슬래시는 자동으로 제거됩니다. 모든 요청은 이 오리진의 /api/v4/ 경로 아래로 전송됩니다.

로깅

SDK는 표준 logging 모듈의 listingsapi 로거를 통해 로그를 기록합니다. DEBUG 수준에서는 모든 요청의 메서드와 URL을 기록하며(GET의 경우 쿼리 매개변수도 기록), 요청 본문과 API 키는 절대 기록하지 않습니다.

Python
import logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

다음 단계