搜索地点 | 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（经过防抖处理），并显示 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 商家资料中发现、尚未纳入管理的链接）。请参阅地点操作链接指南。