ابدأ بالصفحة 1
أرسل fid المكان والصفحة 1. تتبع السجلات الترتيب الذي يوفره معرض المكان.
POST /api/v2/photos
اقرأ حتى 20 عنصر معرض لمكان واحد في الصفحة. احصل على عناوين URL للصور والفيديو بالترتيب الذي تظهر به في المعرض.
للاطلاع على العقد الكامل، راجع وثائق API.
curl https://gmapscrawl.com/api/v2/photos \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: place-photos-page-1-example" \
-d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1}'استبدل fid في المثال بمعرّف ميزة مكانك. الاستجابة محاكاة؛ وعناوين URL للوسائط على example.com هي عناصر نائبة. احتفظ بمفتاح عدم التكرار نفسه والنص نفسه عند إعادة محاولة طلب قيد التنفيذ.
{
"photos": [
{
"photoUrl": "https://example.com/gallery-image.jpg"
},
{
"photoUrl": "https://example.com/gallery-preview.jpg",
"videoUrl": "https://example.com/gallery-video.mp4"
}
],
"next": false,
"total": 2,
"url": "https://www.google.com/maps/uv?pb=!1s0x89c259af336b3341:0xa4969e07ce3108de!15sCgIgAQ",
"params": {
"fid": "0x89c259af336b3341:0xa4969e07ce3108de",
"page": 1
}
}تُرجع API صيغة JSON في الاستجابة نفسها. بعد انتهاء المهلة، أعد المحاولة بالنص نفسه دون تغيير مع Idempotency-Key ذاتها. تُرجع بيانات الاعتماد التجريبية بيانات محاكاة دون استخدام حصتك الفعلية.
ابدأ بمكان
اطلب بيانات الصور والفيديو الوصفية لمكان واحد باستخدام معرّف الميزة الخاص به.
| الحقل | المعنى |
|---|---|
| fid · مطلوب | معرّف ميزة خرائط Google، مثل 0x89c259af336b3341:0xa4969e07ce3108de. استخدم place.dataId من نتيجة Search API، أو معرّف ميزة لديك بالفعل. |
| page · الافتراضي 1 | صفحة مرقّمة موجبة. زدها فقط عندما تحتوي الاستجابة السابقة على next: true. |
لاكتشاف معرّف ميزة، ابحث عن نشاط تجاري باستخدام API سكرابر Google Maps. انسخ place.dataId من الإدخال المطابق في data.businesses ومرّره كـ fid. معرّف المكان أو اسم النشاط التجاري ليس نفس تنسيق الإدخال.
سجلات المعرض
لكل عنصر photoUrl للصورة أو معاينة الفيديو. تتضمن عناصر الفيديو أيضًا videoUrl. يرتبط url ذو المستوى الأعلى بمعرض المكان.
| الحقل | المعنى |
|---|---|
| photoUrl | عنوان URL المتاح للصورة، أو صورة المعاينة لعنصر فيديو. |
| videoUrl | عنوان URL اختياري للفيديو. يكون موجودًا لسجلات الفيديو التي تتضمن مصدر فيديو. |
| url | عنوان URL لمعرض خرائط Google للمكان المطلوب. |
| next | ما إذا كانت صفحة معرض مرقّمة أخرى متاحة. |
| total | العدد في هذه الاستجابة، من صفر إلى 20. هذا ليس الحجم الإجمالي لمعرض المكان. |
| params | fid وpage المُطبَّعان المستخدمان لهذه الاستجابة. |
تُرجع نقطة النهاية كائن الصفحة هذا مباشرة كـ JSON. اقرأ photos من المستوى الأعلى. تُرجع API بيانات وصفية وروابط وسائط. يعتمد توفر صورة أو فيديو على المصدر؛ ولا يضمن عنصر المعرض فيديو قابلًا للتنزيل.
صفحة محدودة في كل مرة
استخدم علامة next المُرجعة لتقرر ما إذا كان سير عملك يحتاج إلى طلب آخر.
أرسل fid المكان والصفحة 1. تتبع السجلات الترتيب الذي يوفره معرض المكان.
يحسب total عناصر المعرض المُرجعة في هذه الاستجابة. الصفحة الفارغة نتيجة صالحة. تحقق من الحقول المتاحة قبل إضافة سجلات إلى تحليلك.
عندما يكون next هو true، زد page واحتفظ بـ fid نفسه. توقف عندما يكون next هو false، أو عندما يكون سير عملك قد حصل على سجلات وسائط كافية.
استكشف مكانًا بصريًا
افحص المعرض المرتبط بنشاط تجاري محدد واحتفظ برابط المعرض المصدر بجانب السجلات المُرجعة.
افصل سجلات الصور عن سجلات الفيديو باستخدام حقل videoUrl الاختياري، واعرض صور المعاينة المتاحة في واجهة البحث الخاصة بك.
دع وكيلًا متصلًا يسترجع صفحة واحدة من بيانات المعرض الوصفية ويسرد روابط الوسائط المتاحة لمزيد من الفحص.
المصادقة والاستخدام
أرسل Authorization: Bearer مع مفتاح يسمح بـ scrapes:write. كل صفحة فعلية ناجحة، بما في ذلك صفحة فارغة، تستخدم وحدة طلب API واحدة. يستخدم REST وMCP حصة API نفسها. إذا كان لديك بيانات اعتماد تجريبية، فإن استجاباتها محاكاة ولا تستهلك الحصة الفعلية.
أرسل Idempotency-Key اختيارية مع طلبك الأول واحتفظ بها مع نص مطابق لإعادة محاولة بعد المهلة. قد تترك مهلة المعالجة وحدة محجوزة. إذا أبلغ خطأ ما أن المحاولة انتهت، اتبع إرشادات إعادة المحاولة قبل إنشاء محاولة جديدة بمفتاح جديد.
تُرجع حتى 20 سجل بيانات وصفية للصور والفيديو لمكان في كل استجابة JSON. لكل سجل photoUrl، وقد تتضمن سجلات الفيديو أيضًا videoUrl. يرتبط url ذو المستوى الأعلى بمعرض المكان.
استخدم place.dataId من نشاط تجاري مطابق في استجابة Search API وأرسله كـ fid. يمكنك أيضًا توفير معرّف ميزة خرائط موجود. أرسل fid نفسه عند طلب صفحات معرض إضافية.
تُرجع نقطة النهاية بيانات وصفية وعناوين URL للوسائط بتنسيق JSON. يمكن لتطبيقك فحص الروابط المتاحة ومصدر المعرض. يحدد توفر المصدر السجلات وعناوين URL المُرجعة؛ ويمكن أن يكون photoUrl صورة معاينة فيديو.
ابدأ بالصفحة 1. يحسب total السجلات في تلك الاستجابة. إذا كان next هو true، اطلب الصفحة التالية بـ fid نفسه ومفتاح عدم تكرار جديد للطلب الجديد. توقف عندما يكون next هو false أو يكون سير عملك قد حصل على سجلات كافية.
تأخذ Photos API معلمتي fid وpage. تُرجع العناصر بترتيب المعرض الذي يوفره المصدر؛ ولا تعرض معلمة sort_by على نمط المراجعات.
نعم. اتصل بعميل MCP متوافق لاستخدام get_google_maps_photos مع بيانات اعتماد API الخاصة بك. تضيف مهارة الوكيل تعليمات سير العمل وبديل REST. تستخدم كل صفحة معرض فعلية ناجحة حصة API المشتركة.
انتقل إلى الخطوة التالية
أنشئ مفتاح API، ووفّر معرّف ميزة مكان، واسترجع بيانات وصفية منظمة للصور والفيديو.