البحث عن المواقع

المعلمات

الاستعلام

الاسم	النوع	مطلوب	الوصف	الافتراضي
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.

استخدم نقطة النهاية هذه للعثور على المواقع باستخدام كلمة مفتاحية نصية حرة. تُطابَق الكلمة المفتاحية مع اسم الموقع وعنوان الشارع والمدينة ومعرّف المتجر، لذا يعثر استعلام واحد مثل ?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 (روابط الإجراءات في Google التي تديرها Listings API) وdiscoveredPlaceActionLinks (روابط موجودة مباشرةً في ملف النشاط التجاري على Google ولا تُدار بعد). راجع دليل روابط إجراءات الأماكن.