사업장

client.locations를 통해 사업장 목록을 조회하고, 사업장을 생성, 수정, 보관 처리, 검색하고 개별 사업장을 조회합니다.

모든 사업장 메서드는 client.locations에 있습니다. 사용하기 전에 SDK를 설치하고 키를 설정해야 합니다. 설치 및 빠른 시작을 참조하세요.

사업장 ID

location_id을 받는 메서드는 숫자 ID(16808) 또는 이를 base64로 인코딩한 값("TG9jYXRpb246MTY4MDg=")을 허용합니다. SDK가 숫자 ID를 자동으로 인코딩하므로 두 형식을 서로 바꿔 사용할 수 있습니다:

Python

# These are equivalentclient.locations.retrieve(16808)client.locations.retrieve("TG9jYXRpb246MTY4MDg=")

`locations.add`

모든 필수 필드를 키워드 인수로 전달하여 한 번의 호출로 사업장을 생성합니다. 사업장을 생성할 때 권장하는 방법입니다. SDK는 클라이언트 측에서 API의 생성 요구 사항을 검증하고 네트워크 호출 전에 ValidationError을 발생시키므로, 잘못된 페이로드는 명확한 메시지와 함께 즉시 실패합니다.

Python

client.locations.add(    *,    name: str,    description: str,    sub_category_id: int,    country_iso: str,    city: str | None = None,    street: str | None = None,    state_iso: str | None = None,    postal_code: str | None = None,    phone: str | None = None,    website: str | None = None,    store_id: str | None = None,    hide_address: bool | None = None,    business_hours: list[dict] | None = None,    service_area: dict | None = None,    place_action_links: list[dict] | None = None,    enabled_site_ids: list[int] | None = None,    additional_fields: dict | None = None,) -> APIObject

인수	유형	설명
`name`	`str`	업체명으로, 2-150자입니다. 필수입니다.
`description`	`str`	업체 설명으로, 최소 200자입니다. 게시 플랫폼에서 등록 정보의 주요 설명문으로 사용합니다. 필수입니다.
`sub_category_id`	`int`	기본 하위 카테고리 ID입니다. 유효한 ID는 `client.subcategories()`으로 확인합니다. 필수입니다.
`country_iso`	`str`	2자리 알파벳 국가 ISO 코드입니다. 지원되는 국가는 `client.countries()`으로 확인합니다. 필수입니다.
`city`	`str`	도시입니다. 주소에 도시를 사용하는 국가에서는 필수이며, `hide_address=True`인 서비스 지역 업체에 한해서만 생략할 수 있습니다.
`street`	`str`	도로명 주소입니다.
`state_iso`	`str`	주 또는 지역 ISO 코드입니다.
`postal_code`	`str`	우편번호 또는 ZIP 코드입니다.
`phone`	`str`	해당 국가의 형식에 맞는지 검증하는 기본 전화번호입니다.
`website`	`str`	업체 웹사이트 URL입니다.
`store_id`	`str`	매장의 고유 코드로, 계정 전체에서 고유해야 합니다.
`hide_address`	`bool`	도로명 주소를 숨깁니다(서비스 지역 업체).
`business_hours`	`list[dict]`	주간 영업시간으로, e.g입니다. `[{"day": "MONDAY", "slots": [...]}]`.
`service_area`	`dict`	서비스 지역 설정: `{businessType, regionCode, placeInfos}`.
`place_action_links`	`list[dict]`	Google 작업 링크로, e.g입니다. `[{"placeActionType": "APPOINTMENT", "uri": "https://...", "isPreferred": True}]`.
`enabled_site_ids`	`list[int]`	요금제에 포함된 사이트 중 일부에만 이 사업장을 게시하려는 경우 사용할 사이트 ID입니다. ID는 `client.plan_sites()`으로 확인합니다.
`additional_fields`	`dict`	페이로드에 그대로 병합되는 추가 camelCase 필드입니다.

클라이언트 측 검증 항목은 다음과 같습니다: name이 2-150자인지, description이 최소 200자인지, sub_category_id과 country_iso이 있는지, hide_address=True인 경우를 제외하고 city이 있는지 확인합니다.

반환값은 생성 페이로드이며, .location에 새 사업장이 포함됩니다. 성공 플래그를 확인할 필요가 없으며, API가 페이로드를 거부하면 SDK가 ValidationError을 발생시킵니다.

Python

result = client.locations.add(  name="Acme Dental",  description=(      "Acme Dental is a family-owned dental practice offering general, "      "cosmetic, and pediatric dentistry in the heart of New York. Our "      "team provides cleanings, fillings, crowns, whitening, and same-day "      "emergency care in a modern, comfortable office with weekend hours "      "and easy online booking for new and returning patients."  ),  sub_category_id=1432,  country_iso="US",  city="New York",  street="123 Jump Street",  state_iso="NY",  postal_code="10013",  phone="6443859313",  website="https://acmedental.example.com",  store_id="NYC-001",  place_action_links=[      {"placeActionType": "APPOINTMENT", "uri": "https://acmedental.example.com/book", "isPreferred": True},  ],  enabled_site_ids=[1, 24, 87],)print("Created:", result.location.id, result.location.name)

`locations.list`

커서 기반 페이지네이션으로 사업장 목록을 조회합니다. SyncPage을 반환합니다.

Python

client.locations.list(    *,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage

Python

# First page of 25page = client.locations.list(first=25)for loc in page:  print(loc.name, loc.city) # Next page manuallyif page.has_more:  page2 = page.next_page() # Auto-paginate all locationsfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

`locations.retrieve`

ID로 단일 사업장을 조회합니다. 해당 ID가 존재하지 않으면 NotFoundError을 발생시킵니다.

Python

client.locations.retrieve(location_id: str | int) -> APIObject

Python

loc = client.locations.retrieve(16808)print(loc.name, loc.street, loc.city)

`locations.list_by_ids`

숫자 또는 base64 형식의 ID 목록으로 여러 사업장을 한 번의 호출로 조회합니다.

Python

client.locations.list_by_ids(location_ids: list[str | int]) -> list[APIObject]

Python

locs = client.locations.list_by_ids([16808, 16809, "TG9jYXRpb246MTQwMjQ="])for loc in locs:  print(loc.id, loc.name)

`locations.list_by_store_codes`

지정한 매장 코드와 일치하는 사업장을 조회합니다.

Python

client.locations.list_by_store_codes(store_codes: list[str]) -> list[APIObject]

Python

locs = client.locations.list_by_store_codes(["SF-001", "NYC-042"])for loc in locs:  print(loc.storeId, loc.name)

`locations.search`

이름, 주소 또는 매장 ID에서 키워드로 사업장을 검색합니다. SyncPage을 반환합니다.

Python

client.locations.search(    query: str,    *,    fields: list[str] | None = None,    first: int | None = None,    after: str | None = None,    before: str | None = None,    last: int | None = None,) -> SyncPage

Python

# Search all fieldspage = client.locations.search("downtown dental", first=10) # Restrict to name onlypage = client.locations.search("Acme Dental", fields=["name"], first=10) for loc in page:  print(loc.name, loc.city)

`locations.create`

camelCase 필드 이름을 사용하는 원시 입력 dict로 사업장을 생성합니다. 키워드 인수와 클라이언트 측 검증을 사용하려면 locations.add을 권장하며, 이미 camelCase 페이로드가 있다면 create을 사용합니다.

Python

client.locations.create(input: dict) -> APIObject

API에서 요구하는 필수 항목은 name, description(최소 200자), subCategoryId, countryIso, city(주소에 도시를 사용하는 국가의 경우)입니다.

Python

result = client.locations.create({  "name": "Acme Dental Brooklyn",  "description": (      "Acme Dental Brooklyn is a family-owned dental practice offering "      "general, cosmetic, and pediatric dentistry. Our team provides "      "cleanings, fillings, crowns, whitening, and same-day emergency "      "care in a modern, comfortable office with weekend hours and easy "      "online booking for new and returning patients across Brooklyn."  ),  "subCategoryId": 1432,  "countryIso": "US",  "city": "Brooklyn",  "street": "88 Court St",  "stateIso": "NY",  "postalCode": "11201",  "phone": "6443859314",  "storeId": "NYC-002",})print("Created:", result.location.id)

`locations.update`

사업장을 수정합니다. id과 변경할 필드(camelCase)를 전달합니다. id은 숫자 또는 base64 형식일 수 있으며, SDK가 자동으로 인코딩합니다.

Python

client.locations.update(input: dict) -> APIObject

Python

result = client.locations.update({  "id": 16808,  "phone": "6443859399",  "street": "125 Jump Street",})print("Updated:", result.location.id)

`locations.archive`

하나 이상의 사업장을 보관 처리합니다.

Python

client.locations.archive(location_ids: list[str | int]) -> APIObject

Python

result = client.locations.archive([16808, 16809])print(result.to_dict())

`locations.cancel_archive`

예약된 보관 처리를 취소합니다.

Python

client.locations.cancel_archive(    location_ids: list[str | int],    selection_type: str,    changed_by: str,) -> APIObject

Python

client.locations.cancel_archive(  [16808],  selection_type="manual",  changed_by="admin@example.com",)