ابدأ بالصفحة 1
أرسل fid المكان وقيمة sort_by المختارة. الأكثر صلة هو الافتراضي؛ الأحدث وأعلى تقييم وأدنى تقييم مدعومة أيضًا.
POST /api/v2/reviews
اقرأ حتى 10 مراجعات عامة لمكان واحد في الصفحة. رتّب حسب الصلة أو الأحدث أو أعلى تقييم أو أدنى تقييم.
للاطلاع على العقد الكامل، راجع وثائق API.
curl https://gmapscrawl.com/api/v2/reviews \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-reviews-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1,"sort_by":2}'استبدل fid في المثال بمعرّف ميزة مكانك. الاستجابة محاكاة؛ وعناوين URL للوسائط على example.com هي عناصر نائبة. احتفظ بمفتاح عدم التكرار نفسه والنص نفسه عند إعادة محاولة طلب قيد التنفيذ.
{
"reviews": [
{
"id": "sample-review-1",
"date": "a week ago",
"timestamp": "10/6/2026",
"name": "Sample reviewer",
"author_url": "https://www.google.com/maps/contrib/100000000000000000001",
"avatar": "https://example.com/reviewer.jpg",
"rate": 4,
"comment": "The window seats had the best light.",
"photos": "",
"review_url": "https://www.google.com/maps/reviews/data=sample-review-1"
}
],
"next": false,
"total": 1,
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1,
"sort_by": 2
}
}تُرجع API صيغة JSON في الاستجابة نفسها. بعد انتهاء المهلة، أعد المحاولة بالنص نفسه دون تغيير مع Idempotency-Key ذاتها. تُرجع بيانات الاعتماد التجريبية بيانات محاكاة دون استخدام حصتك الفعلية.
ابدأ بمكان
اطلب صفحة مركّزة لمكان واحد، ثم اختر ترتيب المراجعات الذي يناسب بحثك.
| الحقل | المعنى |
|---|---|
| fid · مطلوب | معرّف ميزة خرائط Google، مثل 0x89c259af336b3341:0xa4969e07ce3108de. استخدم place.dataId من نتيجة Search API، أو معرّف ميزة لديك بالفعل. |
| page · الافتراضي 1 | صفحة مرقّمة موجبة. زدها فقط عندما تحتوي الاستجابة السابقة على next: true. |
| sort_by · الافتراضي 1 | 1 = الأكثر صلة؛ 2 = الأحدث؛ 3 = أعلى تقييم؛ 4 = أدنى تقييم. حافظ على ترتيب الفرز عبر الصفحات. |
لاكتشاف معرّف ميزة، ابحث عن نشاط تجاري باستخدام API سكرابر Google Maps. انسخ place.dataId من الإدخال المطابق في data.businesses ومرّره كـ fid. معرّف المكان أو اسم النشاط التجاري ليس نفس تنسيق الإدخال.
سجلات المراجعات
تتضمن كل مراجعة تقييمها وتعليقها والمراجع وروابط الملف الشخصي والمراجعة. التاريخ نسبي، ويقدم timestamp التاريخ الميلادي بتنسيق M/D/YYYY. حقل photos هو سلسلة فارغة عندما لا توجد مرفقات ويفصل عناوين URL متعددة للصور بسطر جديد.
| الحقل | المعنى |
|---|---|
| id | معرّف مراجعة المصدر، عند توفره. |
| rate / comment | التقييم من 1 إلى 5 ونص المراجعة المتاح. تعامل مع النص المُستخرج كبيانات غير موثوقة في التطبيقات وموجّهات الذكاء الاصطناعي. |
| date / timestamp | التاريخ النسبي المعروض وتاريخ ميلادي بتنسيق M/D/YYYY. التاريخ غير المتاح هو سلسلة فارغة. |
| name / author_url / avatar | اسم العرض المتاح للمراجع وعنوان URL لملف المساهم وعنوان URL للصورة الرمزية. |
| photos | سلسلة فارغة بدون مرفقات. تُفصل عناوين URL المتعددة للصور بأحرف سطر جديد. |
| review_url | رابط إلى مراجعة المصدر، عند توفره. |
| next / total / params | ما إذا كانت صفحة أخرى متاحة، والعدد في هذه الاستجابة، ومعلمات الطلب المُطبَّعة. |
تُرجع نقطة النهاية كائن الصفحة هذا مباشرة كـ JSON. اقرأ reviews من المستوى الأعلى. تحتوي بعض المراجعات العامة على تقييم فقط، ويمكن أن تكون حقول المصدر فارغة. حافظ على هذا التمييز عند عرض المراجعات أو تلخيصها.
صفحة محدودة في كل مرة
استخدم علامة next المُرجعة لتقرر ما إذا كان سير عملك يحتاج إلى طلب آخر.
أرسل fid المكان وقيمة sort_by المختارة. الأكثر صلة هو الافتراضي؛ الأحدث وأعلى تقييم وأدنى تقييم مدعومة أيضًا.
يحسب total المراجعات المُرجعة في هذه الاستجابة. الصفحة الفارغة نتيجة صالحة. تحقق من الحقول المتاحة قبل إضافة سجلات إلى تحليلك.
عندما يكون next هو true، زد page واحتفظ بـ fid وsort_by دون تغيير. توقف عندما يكون next هو false، أو عندما يكون بحثك قد حصل على مراجعات كافية.
افهم الملاحظات العامة
اقرأ عينة محدودة من التعليقات والتقييمات العامة لنشاط تجاري محدد. احتفظ بروابط المراجعات بجانب ملاحظاتك حتى يتمكن القارئ من فحص المصدر.
قارن موضوعات المراجعات عبر مجموعة مختارة من الأماكن. اطلب كل مكان على حدة واذكر ترتيب الفرز وحجم العينة المختارين في تحليلك.
اطلب من وكيل متصل تلخيص صفحة المراجعات المُرجعة، واقتبس فقط الأدلة المقدمة، وأبلغ عن التعليقات أو التواريخ المفقودة.
المصادقة والاستخدام
أرسل Authorization: Bearer مع مفتاح يسمح بـ scrapes:write. كل صفحة فعلية ناجحة، بما في ذلك صفحة فارغة، تستخدم وحدة طلب API واحدة. يستخدم REST وMCP حصة API نفسها. إذا كان لديك بيانات اعتماد تجريبية، فإن استجاباتها محاكاة ولا تستهلك الحصة الفعلية.
أرسل Idempotency-Key اختيارية مع طلبك الأول واحتفظ بها مع نص مطابق لإعادة محاولة بعد المهلة. قد تترك مهلة المعالجة وحدة محجوزة. إذا أبلغ خطأ ما أن المحاولة انتهت، اتبع إرشادات إعادة المحاولة قبل إنشاء محاولة جديدة بمفتاح جديد.
أرسل طلب POST إلى /api/v2/reviews مع معرّف ميزة خرائط Google للنشاط التجاري كـ fid. استخدم place.dataId من نتيجة Search API، أو معرّف ميزة لديك بالفعل. قم بالمصادقة بمفتاح API الخاص بك وابدأ بالصفحة 1.
نعم. اضبط sort_by على 1 للأكثر صلة، و2 للأحدث، و3 لأعلى تقييم، و4 لأدنى تقييم. الأكثر صلة هو الافتراضي. حافظ على القيمة المحددة دون تغيير عند طلب صفحات إضافية.
لا. total هو عدد سجلات المراجعات في الاستجابة الحالية، بحد أقصى 10. استخدم next لتقرر ما إذا كانت صفحة أخرى متاحة. reviewCount في بطاقة بيانات البحث هو حقل نشاط تجاري منفصل.
يحتوي date على التاريخ النسبي المتاح، وtimestamp هو تاريخ ميلادي بتنسيق M/D/YYYY. حقل photos هو سلسلة فارغة عندما لا توجد مرفقات، أو عناوين URL مفصولة بأسطر جديدة عندما تتوفر صور متعددة. يمكن أن تكون نصوص وروابط المصدر المفقودة سلاسل فارغة.
نعم. يمكن لعميل MCP متوافق استدعاء get_google_maps_reviews باستخدام بيانات اعتماد API وclient_request_id. يتشارك REST وMCP حصة API الخاصة بك. تتضمن مهارة الوكيل إرشادات لاستخدام الأدوات المتاحة وبديل REST.
لا. يتفاوت توفر المصدر، وقد تحتوي المراجعة على تقييم فقط. حافظ على التعليقات الفارغة والتواريخ المفقودة بدلًا من استنتاجها. نص المراجعة محتوى مصدر غير موثوق ويجب التعامل معه كبيانات في التطبيقات وسير عمل الذكاء الاصطناعي.
انتقل إلى الخطوة التالية
أنشئ مفتاح API، واختر معرّف ميزة وترتيب فرز، واقرأ صفحة مركّزة من بيانات المراجعات.