Listings APIListings API
登入

工作流程

透過 client.workflows 使用的複合輔助函式，可執行多個 SDK 呼叫，並傳回 1 個合併結果。

所有工作流程方法都位於 client.workflows 下。每個方法都可取代您原本需要自行撰寫的一連串一般 SDK 呼叫，並傳回在用戶端彙整的單一結果。工作流程背後沒有單一對應的 REST 端點，因此結果中的鍵名是 SDK 自行定義的名稱，而非 REST 回應中實際傳輸的欄位名稱。

由於工作流程會進行多次呼叫，執行時使用的 API 金鑰必須具備存取工作流程所涉及每項資源的權限，而且每次工作流程呼叫都會依底層請求的次數計入速率限制。這些方法接受 location_id，可使用數字或 base64 編碼的 ID，請參閱地點 ID。

workflows.auto_reply_to_reviews

透過一次呼叫，即可使用範本回覆某個地點的評論。您可以用此方法維持正面評論的回覆率，同時手動處理其餘評論。

Python
client.workflows.auto_reply_to_reviews(    location_id: str | int,    *,    template: str = "Thank you for your feedback!",    min_rating: int = 4,    only_unanswered: bool = True,    dry_run: bool = False,) -> list[dict[str, Any]]
參數型別說明
location_idstr | int要處理的地點。
templatestr符合條件之評論的回覆文字。{rating} 會替換為該評論的評分。
min_ratingint只回覆評分等於或高於此值的評論。預設為 4。
only_unansweredbool略過已有回覆的評論。預設為 True。
dry_runbool傳回預計回覆的內容，但不發布。預設為 False。

此方法可取代以下呼叫流程：先透過 auto_paging_iter() 分頁讀取 reviews.list，再針對每則同時符合兩項篩選條件的評論，各呼叫一次 reviews.respond。

Python
# See what would be sent, without postingplan = client.workflows.auto_reply_to_reviews(  16808,  template="Thanks for the {rating}-star review!",  min_rating=4,  dry_run=True,)for entry in plan:  print(entry["id"], entry["rating"], entry["status"]) # Then post for realresults = client.workflows.auto_reply_to_reviews(16808, min_rating=4)print(f"Replied to {len(results)} reviews")

傳回一般的 dict 清單，每則已處理的評論各有一筆，每筆都包含 id、rating、reply 和 status。請先使用 dry_run=True 執行：傳回項目的 status 會設為 dry_run，讓您在發布任何回覆之前檢查選取的評論。

workflows.listings_health_audit

透過一次呼叫，即可取得某個地點的商家資訊整體狀況：進階商家資訊、語音商家資訊、重複商家資訊，以及分數。您可以用此方法建立個別地點的健康狀況面板，取代 3 次獨立呼叫。

Python
client.workflows.listings_health_audit(location_id: str | int) -> APIObject

此方法可取代針對同一地點進行的 listings.premium、listings.voice 和 listings.duplicates 呼叫，並依 syncStatus 統計進階商家資訊結果的數量。

Python
audit = client.workflows.listings_health_audit(16808)print(f"Health score: {audit.health_score}%")print(f"Synced: {audit.synced_count} of {len(audit.premium)}")print(f"Duplicates found: {len(audit.duplicates)}")for issue in audit.issues:  print(issue.get("site"), issue.get("syncStatus"))

傳回 APIObject，其中包含 location_id、premium、voice、duplicates、synced_count、issue_count、issues 和 health_score。health_score 是 syncStatus 為 SYNCED 的進階商家資訊所占比例，以整數百分比表示；沒有進階商家資訊時則為 0。issues 包含 syncStatus 存在且不為 SYNCED 的進階商家資訊。

workflows.weekly_reputation_report

取得單一地點在指定日期區間內的評論、評論分析、商家檔案分析，以及商家資訊同步狀態。由於此方法會進行 5 次呼叫，請將其用於定期報告，而非即時儀表板。

Python
client.workflows.weekly_reputation_report(    location_id: str | int,    *,    start_date: str | None = None,    end_date: str | None = None,) -> APIObject

start_date 和 end_date 都是 YYYY-MM-DD 字串，兩者皆為選填。此方法可取代 reviews.analytics.overview、使用 first=50 的 reviews.list、analytics.google、analytics.bing 和 listings.premium 呼叫，並將日期區間傳遞給每個接受此參數的呼叫。

Python
report = client.workflows.weekly_reputation_report(  16808,  start_date="2026-09-01",  end_date="2026-09-07",)print(report.review_summary.get("averageRating"))print(report.analytics.get("google", {}).get("views"))print(report.listings_health.get("sync_rate"))

傳回 APIObject，其中包含 location_id、review_summary（評論分析總覽）、recent_reviews（該區間內最多 50 則評論）、analytics（包含 google 和 bing 的 dict），以及 listings_health（包含 total、synced 和 sync_rate 的 dict）。sync_rate 是已格式化的百分比字串；該地點沒有進階商家資訊時則為 N/A。

另請參閱