Listings APIListings API
登入

為尚無商家檔案的地點建立 Google Business Profile

在已連結的 Google 帳戶下，為地點提交全新的 Google Business Profile，然後透過該地點、其商家資訊及 webhooks 追蹤驗證進度。

只有在 Google 商家資訊已存在時，才能進行比對和連結。新店面尚無商家資訊，因此您需要要求 API 在已連結的 Google 帳戶下建立商家資訊。建立作業採非同步方式進行，且 Google 會依自己的時程驗證商家檔案，因此本指南大部分內容著重於追蹤結果。

1. 確認地點尚無 Google 商家資訊

讀取地點的進階商家資訊，並找出 site.name 為 Google Maps 的資料列。尚未出現在 Google 上的地點會顯示 REQUIRING_ACTION，且 connectedAccountId 為 null。

Google row
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

如果該資料列已是 SYNCED，或已設定 connectedAccountId，則該地點已有 Google 商家資訊，本指南不適用。請改為連結或更新該商家資訊。

2. 選擇資料夾（選用）

Google 會將帳戶下的商家資訊整理至資料夾中，這些資料夾也稱為帳戶群組。列出已連結帳戶的資料夾，若擁有者希望將新商家檔案放在特定群組中，請將其中一個資料夾作為 folderId 傳入。若要在帳戶根層級建立商家檔案，請略過此步驟。

Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

請原樣使用 folderId；它是 accounts/{id} 字串，而非數字。當 Google 未回報 locationCount 時，其值可能為 null。此端點僅適用於 GoogleAccount 連線。

3. 建立商家資訊

傳送地點的 base64 id 和帳戶；如果您選擇了資料夾，也請一併傳送。回應僅表示請求已受理，並無其他含義。

Create listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": { "clientMutationId": null, "success": true, "errors": null }  }}

success: true 表示已啟動建立作業，不代表商家檔案已上線。Google 會在發布前審查每個新商家檔案，這可能需要數天。當 success 為 false 時，errors 會說明原因：地點缺少必要欄位、已有 Google 商家資訊、已封存，或已連結的帳戶已不再有效。

4. 追蹤地點的驗證狀態

每次讀取地點時，都會傳回包含 status 和 message 的 googleVerificationStatus。再次讀取該地點，即可查看 Google 目前的處理進度。

Verification status
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}
status意義是否為最終狀態
NOT_CONNECTED尚未附加 Google 商家資訊。在步驟 3 生效前，預期會出現此狀態。否
NOT_VERIFIED商家資訊已存在，尚未開始驗證。否
PENDING_VERIFICATIONGoogle 正在驗證商家檔案。否
UNDER_REVIEWGoogle 正在審查商家檔案。否
VERIFIED商家檔案已上線。是
SUSPENDEDGoogle 已停權此商家檔案。是
DUPLICATEGoogle 判定此商家檔案與現有商家檔案重複。是
ERROR_WHILE_FETCHING無法從 Google 讀取狀態。請稍後重試。是

對於需要數天的流程，每天讀取一次就足夠。如果您一次檢查多個地點，遇到 429 時，請遵循 Retry-After。

5. 追蹤商家資訊中的 Google 資料列

步驟 1 中的進階商家資訊資料列會從商家資訊端追蹤相同的進度。重新執行步驟 1 的呼叫，並讀取 syncStatus、verified 和 listingUrl。

syncStatus意義
REQUIRING_ACTION尚未建立任何商家資訊，或帳戶有需要處理的問題。請參閱 displayStatus。
IN_PROGRESS已提交至 Google，正在等待回應。
PENDING_APPROVAL正在等待 Google 核准。
SYNCED已上線。listingUrl 已填入值，且 connectedAccountId 會指出帳戶名稱。
FAILEDGoogle 已拒絕此次提交。syncIssue 會說明原因。

6. 監聽驗證 webhook

如果已在儀表板中設定 webhook URL，便會有兩種事件涵蓋最終狀態，因此您不必輪詢。這兩種事件都包含 location_id，且一律具有 data.connected_account_id: null。

事件觸發時機data 欄位
connection.google_verification_verified商家檔案進入 VERIFIED 狀態時。platform: "google"
connection.google_verification_failed商家檔案進入 SUSPENDED、DUPLICATE（failure_type: "rejected"）或 ERROR_WHILE_FETCHING（failure_type: "transient"）狀態時。platform, failure_type, reason
JSON
{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

只有 transient 失敗才值得重試。進行中的狀態完全不會發出事件，因此沒有事件並不代表任何狀態：驗證進行期間，請依照步驟 4 讀取 googleVerificationStatus。

後續步驟