/api/v4/locationsسرد جميع المواقع
يعيد قائمة بالمواقع في حسابك مقسّمة إلى صفحات باستخدام مؤشرات.
المعلمات
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| first | integer | اختياري | Number of records to fetch from the start of the connection (forward pagination). Combine with `after`. | 50 |
| last | integer | اختياري | Number of records to fetch from the end of the connection (backward pagination). Combine with `before`. | — |
| after | string | اختياري | Cursor to fetch records after. Pass `pageInfo.endCursor` from the previous page. | — |
| before | string | اختياري | Cursor to fetch records before, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from. `pageInfo` carries no `startCursor` field, so the edge cursor is the value to use. | — |
| filter | string | اختياري | JSON-encoded filter object to narrow the result set (e.g. by approval status or sync state). | — |
الاستجابات
200Cursor-paginated connection of locations. Each edge exposes a `cursor` and a `node` (the full location).
{ "data": { "allLocations": { "edges": [ { "cursor": "TG9jYXRpb246MTgwMDI4OQ==", "node": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "accountId": 12345, "accountName": "owner@brightsmile-dental.com", "name": "Jenny Home", "approved": "APPROVED", "archived": false, "archivalScheduledAt": null, "archivedAt": null, "street": "600 Congress Ave, Suite 200", "city": "Austin", "stateIso": "TX", "stateName": "Texas", "postalCode": "78701", "countryIso": "US", "countryCode": "1", "latitude": "30.2711286", "longitude": "-97.7436995", "phone": "5125550142", "additionalPhones": [], "bizUrl": null, "hideAddress": false, "storeId": null, "categoryId": 15, "subCategoryId": 1432, "subCategoryName": "Restaurants", "additionalCategoryIds": [], "additionalCategoryNames": [], "description": "This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin, offering spacious duplex living with easy access to the surrounding South Congress area and downtown Austin.", "businessHours": [], "package": "PREMIUM", "planId": 3797, "planName": "Launch", "temporarilyClosed": false, "ownerEmail": null, "ownerName": null, "googleVerificationStatus": { "status": "NOT_CONNECTED", "message": null }, "voiceStatus": 3, "uid": "3c92283c-6145-4a43-8a62-0c15fd712021", "createdDate": "July 06, 2026", "lastUpdatedDate": "July 06, 2026", "updatedAt": "2026-07-06T18:33:29.664Z", "placeActionLinks": [ { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": "locations/1944.../placeActionLinks/54ada85bc246058a", "submissionStatus": "success", "submissionMessage": "Already up to date on Google.", "lastSubmittedAt": "2026-07-08T12:14:36Z" } ], "discoveredPlaceActionLinks": [ { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "name": "locations/1944.../placeActionLinks/abc123", "providerType": "MERCHANT", "isEditable": true } ] } } ], "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "total": 1 } } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يتنقل عبر جميع المواقع في حسابك صفحةً تلو الأخرى. تُرتَّب النتائج حسب تاريخ الإنشاء (الأحدث أولًا). تحمل كل حافة cursor (رمزًا معتمًا بتنسيق base64، يُفك ترميزه للموقع إلى Location:<databaseId>) وnode يحتوي على سجل الموقع الكامل.
حالة استخدام: مزامنة جميع المواقع مع نظامك الخاص. ابدأ بـ ?first=50، واقرأ pageInfo.hasNextPage، وإذا كانت قيمته true، فاطلب الصفحة التالية باستخدام ?first=50&after=<pageInfo.endCursor>. كرر ذلك حتى تصبح قيمة hasNextPage هي false. لاستئناف استكمال البيانات السابقة من الطرف الآخر، استخدم last + before مع cursor للحافة الأولى في الصفحة التي تنتقل منها إلى الخلف. قيمة id للعقدة بترميز base64 هي المعرّف الذي تتوقعه جميع نقاط النهاية الأخرى، لذا مرّرها إلى جلب المواقع حسب المعرّفات أو المساعدات الصوتية أو تحديث موقع.
حالة استخدام: مجموعة فرعية مصفّاة. مرّر كائنًا مرمّزًا بتنسيق JSON في filter لتصفية النتائج على جانب الخادم (حسب حالة الموافقة مثلًا) بدلًا من جلب جميع الصفحات وتصفيتها على جانب العميل. يُبقي ذلك الحسابات الكبيرة ضمن حدود معدل الطلبات.
تنبيه بشأن تقسيم النتائج إلى صفحات وحدود معدل الطلبات: المؤشرات معتمة: لا تنشئ أيًّا منها يدويًا أبدًا؛ أعد دائمًا إرسال مؤشر أعادته واجهة API، سواء كان pageInfo.endCursor عند التقدم إلى الأمام أو cursor الخاص بإحدى الحواف عند الرجوع إلى الخلف (لا يحتوي pageInfo على startCursor). استخدم إما first/after (للأمام) أو last/before (للخلف)، ولا تستخدم الاتجاهين معًا. حلقات جلب الصفحات المتلاحقة بسرعة هي السبب الأكثر شيوعًا للاستجابات 429؛ التزم بترويسة Retry-After وتجنب وجود أكثر من طلب صفحة واحد قيد التنفيذ في الوقت نفسه.
يُعاد لكل موقع placeActionLinks (روابط الإجراءات على Google التي تديرها Listings API) وdiscoveredPlaceActionLinks (الروابط الموجودة مباشرةً في ملف النشاط التجاري على Google والتي لا تُدار بعد). راجع دليل روابط إجراءات الأماكن لمعرفة كيفية قراءتها وضمّها إلى الروابط المُدارة وإدارتها.
curl -X GET 'https://listingsapi.com/api/v4/locations' \ -H "Authorization: API $LISTINGSAPI_KEY"