搜尋地點 | Listings API

參數

查詢

名稱	類型	必填	說明	預設值
query	string	選填	Search keyword matched against location name, street address, city, and store ID. Omit to page through every location.	—
filter	string	選填	JSON-encoded filter object to narrow results (for example by approval status).	—
first	integer	選填	Number of records to fetch, starting from the most recent.	50
after	string	選填	Cursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.	—

回應

200Cursor-paginated list of matching locations.

Response

{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "accountId": 12345,            "accountName": "owner@brightsmile-dental.com",            "addOns": [],            "additionalCategoryIds": [],            "additionalCategoryNames": [],            "additionalGbpSiteCategoryIds": [],            "additionalGbpSiteCategoryNames": [],            "additionalInfo": null,            "additionalPhones": [],            "aiAnalyticsEnabled": false,            "approved": "APPROVED",            "archivalScheduledAt": null,            "archived": false,            "archivedAt": null,            "bizUrl": null,            "bizUrlUtm": false,            "bookingUrl": null,            "businessHours": [],            "cancellationScheduledAt": null,            "categoryId": 15,            "city": "Austin",            "clientName": "owner@brightsmile-dental.com",            "contentPreferredLanguage": "ENGLISH",            "countryCode": "1",            "countryIso": "US",            "createErrors": [],            "createdDate": "July 06, 2026",            "customAttributes": [],            "databaseId": 1800289,            "defaultAgencyTag": "ownerbrightsmiledentalcom",            "description": "This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin.",            "discoveredPlaceActionLinks": [],            "enabledSiteIds": [],            "facebookUrl": null,            "franchise": false,            "googleAdsPhone": null,            "googleVerificationStatus": { "message": null, "status": "NOT_CONNECTED" },            "googleplusUrl": null,            "hideAddress": false,            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "instagramUrl": null,            "isRestaurant": true,            "lastUpdatedDate": "July 06, 2026",            "latitude": "30.2711286",            "linkedinUrl": null,            "locationPhotos": [],            "longitude": "-97.7436995",            "managedServiceSiteBuckets": [],            "managedServiceSites": [],            "moreHours": [],            "name": "Jenny Home",            "offeringsUrl": null,            "ownerEmail": null,            "ownerName": null,            "package": "PREMIUM",            "paymentMethods": [],            "phone": "5125550142",            "pinterestUrl": null,            "placeActionLinks": [],            "planId": 3797,            "planName": "Launch",            "postalCode": "78701",            "primaryGbpSiteCategoryId": null,            "primaryGbpSiteCategoryName": null,            "publisherAttributes": [],            "reservationUrl": null,            "serviceArea": null,            "serviceItems": [],            "stateIso": "TX",            "stateName": "Texas",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "street1": null,            "subCategoryId": 1432,            "subCategoryName": "Restaurants",            "tagline": null,            "temporarilyClosed": false,            "tiktokUrl": null,            "toplineMessage": null,            "twitterUrl": null,            "uid": "3c92283c-6145-4a43-8a62-0c15fd712021",            "updatedAt": "2026-07-06T18:33:29.664Z",            "videos": [],            "voiceStatus": 3,            "yearOfIncorporation": null,            "youtubeUrl": null          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

使用此端點，透過自由輸入的文字關鍵字尋找地點。關鍵字會與地點名稱、街道地址、城市和門市 ID 比對，因此，無論使用者輸入的是品牌、街道還是內部門市代碼，像 ?query=Jenny 這樣的單一查詢都能找到「Jenny Home」。

使用案例：隨輸入即時搜尋的地點選擇器。 若要在儀表板中支援「搜尋您的地點」搜尋框，請在每次按鍵輸入時呼叫 GET /locations/search?query=<term>&first=10（請加上 debounce），並顯示 edges[].node.name 與 databaseId。由於節點包含完整地址、類別和 approved 狀態，您無需再次查詢，就能顯示資訊豐富的結果列。

使用案例：與您自己的系統核對。 若要在推送更新前確認門市已存在於 Listings API 中，請使用您的 storeId 值搜尋；若 edges 陣列為空，表示該地點尚未建立。

分頁與注意事項。

結果採用游標分頁。將上一次回應中的 pageInfo.endCursor 作為 after 傳入，以取得下一頁，並在 hasNextPage 為 false 時停止。請注意，單頁的筆數是 pageInfo.total，而非 totalCount。
省略 query 時，會傳回未經篩選的地點（受 first 限制），這是逐頁取得整個帳戶地點的便利方式。
搜尋會共用帳戶的速率限制。遇到 429 時，請依照 Retry-After 標頭延後重試。

每個符合條件的地點都會傳回 placeActionLinks（Listings API 管理的 Google 動作連結）和 discoveredPlaceActionLinks（直接在商家的 Google 商家檔案上找到、但尚未納入管理的連結）。請參閱地點動作連結指南。