Listings APIListings API
로그인

빠른 시작

Listings API에 연결하고, 사업장 목록을 조회하고, 한 번의 호출로 사업장을 생성하고, 리뷰에 답글을 작성합니다.

1. API 키 설정

Listings API 개발자 대시보드의 API Keys → New key에서 키를 발급받습니다. SDK는 LISTINGSAPI_KEY 환경 변수에서 키를 자동으로 읽습니다.

bash
export LISTINGSAPI_KEY="your-api-key"

2. 사업장 목록 조회

quickstart.py
import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, "--", loc.city, loc.stateIso) print(f"\nShowing {len(page)} locations, has_more={page.has_more}")
bash
python quickstart.py

예상 출력:

bash
Acme Dental Downtown -- New York NYAcme Dental Midtown -- New York NYAcme Dental Brooklyn -- Brooklyn NY Showing 3 locations, has_more=False

모든 페이지를 자동으로 요청하려면 client.locations.list(first=100).auto_paging_iter()을 사용합니다. 커서에 따라 페이지를 순회하므로 커서를 직접 관리할 필요가 없습니다.

3. 한 번의 호출로 사업장 생성

locations.add()은 모든 필수 필드를 키워드 인수로 받고, 네트워크 호출 전에 클라이언트 측에서 해당 필드의 유효성(이름 길이, 설명의 최소 200자 요건, 카테고리, 국가, 도시)을 검사하므로 잘못된 페이로드는 명확한 ValidationError과 함께 즉시 실패합니다.

Python
import listingsapi client = listingsapi.ListingsAPI() result = client.locations.add(  name="Acme Dental Uptown",  description=(      "Acme Dental Uptown is a family-owned dental practice on the Upper "      "West Side of New York offering preventive care, cosmetic dentistry, "      "orthodontics, and emergency appointments. Our board-certified team "      "combines modern equipment with a gentle, patient-first approach."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="482 Columbus Ave",  state_iso="NY",  postal_code="10024",  phone="6443859313",) print(result.location.id)print(result.location.name)

게시 플랫폼은 설명을 등록 정보의 주요 본문으로 사용하므로 API는 최소 200자를 요구합니다. 유효한 sub_category_id 값은 client.subcategories()에서 가져옵니다.

새 ID는 TG9jYXRpb246MTY4MDg=과 같은 base64 문자열로 반환됩니다. SDK에서 사업장 ID를 받는 모든 곳에서 숫자 ID와 base64 ID를 서로 바꿔 사용할 수 있으므로 client.locations.retrieve(16808)과 client.locations.retrieve("TG9jYXRpb246MTY4MDg=")는 동일한 사업장을 조회합니다.

4. 리뷰에 답글 작성

사업장의 리뷰 목록을 조회한 다음 리뷰의 interactionId을 사용하여 답글을 작성합니다.

Python
import listingsapi client = listingsapi.ListingsAPI() reviews = client.reviews.list(16808, first=10, rating_filters=[4, 5])for review in reviews:  print(review.rating, "-", review.get("content")) # A page can come back empty, and not every review is repliable: some sites# allow one owner reply per review, and some are read-only for the account.repliable = [r for r in reviews if r.get("canRespond")]if not repliable:  print("nothing to reply to")else:  client.reviews.respond(      interaction_id=repliable[0].interactionId,      content="Thank you for the kind review! We look forward to seeing you again soon.",  )

답글을 작성하기 전에 canRespond을 확인하고, 페이지가 비어 있지 않은지 먼저 확인한 후에만 인덱스로 페이지의 항목에 접근합니다. 빈 페이지에서 reviews[0]을 사용하면 IndexError이 발생하며, 원본 플랫폼에서 답글 작성을 마감한 리뷰에 답글을 작성하면 API가 아닌 게시 플랫폼에서 실패합니다.

플랫폼이 답글을 거부하면 HTTP 상태가 200이어도 SDK가 ValidationError을 발생시키므로 success 플래그를 직접 확인할 필요가 없습니다.

5. 오류 처리

Python
import listingsapi try:  client = listingsapi.ListingsAPI(api_key="bad-key")  client.locations.list()except listingsapi.AuthenticationError as e:  print("Invalid key:", e.code)

유효하지 않은 키를 사용하면 플랫폼 코드 SY90005이 포함된 HTTP 401이 반환되며 SDK는 AuthenticationError을 발생시킵니다. 동일한 오류 코드가 200 본문에 포함되어 반환되는 경우에도 SDK는 이를 방어적으로 처리합니다. 전체 예외 계층 구조는 오류 처리를, HTTP 상태 매트릭스는 오류 코드 참조를 확인합니다.

다음 단계