POST /api/v2/photos

API سكرابر صور Google Maps

اقرأ حتى 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 هي عناصر نائبة. احتفظ بمفتاح عدم التكرار نفسه والنص نفسه عند إعادة محاولة طلب قيد التنفيذ.

الاستجابة

JSON توضيحي
{
  "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 ذاتها. تُرجع بيانات الاعتماد التجريبية بيانات محاكاة دون استخدام حصتك الفعلية.

ابدأ بمكان

افتح المعرض العام لمكان.

اطلب بيانات الصور والفيديو الوصفية لمكان واحد باستخدام معرّف الميزة الخاص به.

معلمات طلب API سكرابر صور Google Maps
الحقلالمعنى
fid · مطلوبمعرّف ميزة خرائط Google، مثل 0x89c259af336b3341:0xa4969e07ce3108de. استخدم place.dataId من نتيجة Search API، أو معرّف ميزة لديك بالفعل.
page · الافتراضي 1صفحة مرقّمة موجبة. زدها فقط عندما تحتوي الاستجابة السابقة على next: true.

لاكتشاف معرّف ميزة، ابحث عن نشاط تجاري باستخدام API سكرابر Google Maps. انسخ place.dataId من الإدخال المطابق في data.businesses ومرّره كـ fid. معرّف المكان أو اسم النشاط التجاري ليس نفس تنسيق الإدخال.

سجلات المعرض

روابط الصور وروابط الفيديو والمعرض المصدر.

لكل عنصر photoUrl للصورة أو معاينة الفيديو. تتضمن عناصر الفيديو أيضًا videoUrl. يرتبط url ذو المستوى الأعلى بمعرض المكان.

حقول استجابة API سكرابر صور Google Maps
الحقلالمعنى
photoUrlعنوان URL المتاح للصورة، أو صورة المعاينة لعنصر فيديو.
videoUrlعنوان URL اختياري للفيديو. يكون موجودًا لسجلات الفيديو التي تتضمن مصدر فيديو.
urlعنوان URL لمعرض خرائط Google للمكان المطلوب.
nextما إذا كانت صفحة معرض مرقّمة أخرى متاحة.
totalالعدد في هذه الاستجابة، من صفر إلى 20. هذا ليس الحجم الإجمالي لمعرض المكان.
paramsfid وpage المُطبَّعان المستخدمان لهذه الاستجابة.

تُرجع نقطة النهاية كائن الصفحة هذا مباشرة كـ JSON. اقرأ photos من المستوى الأعلى. تُرجع API بيانات وصفية وروابط وسائط. يعتمد توفر صورة أو فيديو على المصدر؛ ولا يضمن عنصر المعرض فيديو قابلًا للتنزيل.

صفحة محدودة في كل مرة

اقرأ حتى 20 عنصر معرض في كل استجابة.

استخدم علامة next المُرجعة لتقرر ما إذا كان سير عملك يحتاج إلى طلب آخر.

01

ابدأ بالصفحة 1

أرسل fid المكان والصفحة 1. تتبع السجلات الترتيب الذي يوفره معرض المكان.

02

افحص الصفحة الحالية

يحسب total عناصر المعرض المُرجعة في هذه الاستجابة. الصفحة الفارغة نتيجة صالحة. تحقق من الحقول المتاحة قبل إضافة سجلات إلى تحليلك.

03

تابع بشكل مدروس

عندما يكون next هو true، زد page واحتفظ بـ fid نفسه. توقف عندما يكون next هو false، أو عندما يكون سير عملك قد حصل على سجلات وسائط كافية.

استكشف مكانًا بصريًا

أدخل بيانات المعرض الوصفية في سير عمل البحث لديك.

01

أبحاث بطاقات بيانات الأنشطة التجارية

افحص المعرض المرتبط بنشاط تجاري محدد واحتفظ برابط المعرض المصدر بجانب السجلات المُرجعة.

02

تنظيم الصور والفيديو

افصل سجلات الصور عن سجلات الفيديو باستخدام حقل videoUrl الاختياري، واعرض صور المعاينة المتاحة في واجهة البحث الخاصة بك.

03

مراجعة المعرض بمساعدة الوكيل

دع وكيلًا متصلًا يسترجع صفحة واحدة من بيانات المعرض الوصفية ويسرد روابط الوسائط المتاحة لمزيد من الفحص.

المصادقة والاستخدام

استخدم مفتاح API الخاص بك لكل صفحة.

حصة API مشتركة

أرسل Authorization: Bearer مع مفتاح يسمح بـ scrapes:write. كل صفحة فعلية ناجحة، بما في ذلك صفحة فارغة، تستخدم وحدة طلب API واحدة. يستخدم REST وMCP حصة API نفسها. إذا كان لديك بيانات اعتماد تجريبية، فإن استجاباتها محاكاة ولا تستهلك الحصة الفعلية.

عرض خطط وحدود API ←

اجعل عمليات إعادة المحاولة مرتبطة بالطلب

أرسل Idempotency-Key اختيارية مع طلبك الأول واحتفظ بها مع نص مطابق لإعادة محاولة بعد المهلة. قد تترك مهلة المعالجة وحدة محجوزة. إذا أبلغ خطأ ما أن المحاولة انتهت، اتبع إرشادات إعادة المحاولة قبل إنشاء محاولة جديدة بمفتاح جديد.

اقرأ إرشادات الأخطاء وإعادة المحاولة ←

الأسئلة الشائعة

ماذا تُرجع API سكرابر صور Google Maps؟

تُرجع حتى 20 سجل بيانات وصفية للصور والفيديو لمكان في كل استجابة JSON. لكل سجل photoUrl، وقد تتضمن سجلات الفيديو أيضًا videoUrl. يرتبط url ذو المستوى الأعلى بمعرض المكان.

كيف أحصل على معرّف ميزة معرض مكان؟

استخدم place.dataId من نشاط تجاري مطابق في استجابة Search API وأرسله كـ fid. يمكنك أيضًا توفير معرّف ميزة خرائط موجود. أرسل fid نفسه عند طلب صفحات معرض إضافية.

هل تنزّل Photos API ملفات الصور أو الفيديو؟

تُرجع نقطة النهاية بيانات وصفية وعناوين URL للوسائط بتنسيق JSON. يمكن لتطبيقك فحص الروابط المتاحة ومصدر المعرض. يحدد توفر المصدر السجلات وعناوين URL المُرجعة؛ ويمكن أن يكون photoUrl صورة معاينة فيديو.

كيف أرقّم صفحات معرض خرائط Google؟

ابدأ بالصفحة 1. يحسب total السجلات في تلك الاستجابة. إذا كان next هو true، اطلب الصفحة التالية بـ fid نفسه ومفتاح عدم تكرار جديد للطلب الجديد. توقف عندما يكون next هو false أو يكون سير عملك قد حصل على سجلات كافية.

هل ترتيب المعرض قابل للتهيئة؟

تأخذ Photos API معلمتي fid وpage. تُرجع العناصر بترتيب المعرض الذي يوفره المصدر؛ ولا تعرض معلمة sort_by على نمط المراجعات.

هل يمكن لوكيل ذكاء اصطناعي استرجاع بيانات المعرض الوصفية؟

نعم. اتصل بعميل MCP متوافق لاستخدام get_google_maps_photos مع بيانات اعتماد API الخاصة بك. تضيف مهارة الوكيل تعليمات سير العمل وبديل REST. تستخدم كل صفحة معرض فعلية ناجحة حصة API المشتركة.

انتقل إلى الخطوة التالية

استكشف معرض مكان واحد.

أنشئ مفتاح API، ووفّر معرّف ميزة مكان، واسترجع بيانات وصفية منظمة للصور والفيديو.