صور المكان

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

تُعد خدمة Place Photo (صور المكان) جزءًا من Places API، وهي واجهة برمجة تطبيقات للقراءة فقط تسمح لك بإضافة محتوى فوتوغرافي عالي الجودة إلى تطبيقك. تتيح لك خدمة "صور المكان" الوصول إلى ملايين الصور المخزنة في قاعدة بيانات الأماكن. عندما تحصل على معلومات عن المكان باستخدام طلب "تفاصيل المكان"، سيتم عرض مراجع الصور لمحتوى الصور الفوتوغرافية ذي الصلة. كما تعرض طلبات "العثور على مكان" و"بحث عن أماكن قريبة" و"بحث نصي" مرجعًا واحدًا للصورة لكل مكان، عندما يكون ذلك مناسبًا. باستخدام خدمة الصور، يمكنك بعد ذلك الوصول إلى الصور المشار إليها وتغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.

طلبات صور الأماكن

طلب صورة المكان هو عنوان URL يستخدم HTTP للنموذج التالي:

https://maps.googleapis.com/maps/api/place/photo?parameters

يجب توفير معلَمات معيّنة لبدء طلب بحث. وكما هو الحال بالنسبة إلى عناوين URL، يتم فصل جميع المعلمات باستخدام حرف العطف (&). يتم تعداد قائمة المعلمات وقيمها المحتملة أدناه.

Required parameters

  • photo_reference

    A string identifier that uniquely identifies a photo. Photo references are returned from either a Place Search or Place Details request.

  • maxheight or maxwidth

    maxheight specifies the maximum desired height, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    maxwidth specifies the maximum desired width, in pixels, of the image. If the image is smaller than the values specified, the original image will be returned. If the image is larger in either dimension, it will be scaled to match the smaller of the two dimensions, restricted to its original aspect ratio.

    Both the maxheight and maxwidth properties accept an integer between 1 and 1600.

    You must specify either maxheight, or maxwidth, or both.

مراجع الصور

ويجب أن تشتمل جميع الطلبات المقدّمة لخدمة "صور المكان" على photo_reference يتم إرجاعه في الرد على طلب "العثور على مكان" أو "بحث عن مكان قريب" أو "البحث النصي" أو "تفاصيل المكان". سيتضمّن الردّ على هذه الطلبات الحقل "photos[]" إذا كان المكان يتضمّن محتوًى فوتوغرافيًا ذي صلة.

ملاحظة: يختلف عدد الصور التي يتم إرجاعها حسب الطلب.

  • يؤدي طلب "البحث عن مكان" أو "البحث عن قرب" أو "البحث النصي" إلى عرض عنصر photo واحد كحدّ أقصى في المصفوفة.
  • يعرض طلب "تفاصيل المكان" ما يصل إلى عشرة عناصر photo.

يحتوي كل عنصر photo على الحقول التالية:

  • photo_reference — سلسلة تُستخدم لتحديد الصورة عند تنفيذ طلب صورة.
  • height — الحد الأقصى لارتفاع الصورة.
  • width — الحد الأقصى لعرض الصورة.
  • html_attributions[] — يحتوي على أي سمات مطلوبة. سيكون هذا الحقل موجودًا دائمًا، ولكنه قد يكون فارغًا.

يتم الحصول على الصور التي تعرضها خدمة الصور من مجموعة متنوعة من المواقع، بما في ذلك مالكي الأنشطة التجارية والصور التي يساهم بها المستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون نَسب العمل، أو سيتم تضمين الإسناد المطلوب كجزء من الصورة. وإذا كان عنصر photo المعروض يتضمّن قيمة في الحقل html_attributions، عليك تضمين الإشارة الإضافية في تطبيقك أينما تعرض الصورة.

يوضح المثال التالي طلب تفاصيل مكان:

curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"

يمكنك الاطّلاع أدناه على مثال على مصفوفة photos[] في الردّ.

...
"photos" : [
   {
      "html_attributions" : [],
      "height" : 853,
      "width" : 1280,
      "photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
   }
...

مثال على صورة مكان

إليك مثال على الطلب. سيعرض هذا الطلب الصورة المشار إليها مع تغيير حجمها إلى أن يبلغ عرضها 400 بكسل على الأكثر.

https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q&key=YOUR_API_KEY

الردّ على صورة المكان

سيكون الرد على طلب "صورة مكان" ناجحًا على هيئة صورة. سيعتمد نوع الصورة على نوع الصورة التي تم إرسالها في الأصل.

إذا تجاوز طلبك الحصة المتاحة، سيعرض الخادم حالة HTTP 403 وسيعرض الصورة أدناه للإشارة إلى تجاوز الحصة:

صورة تم تجاوز الحصة المحدّدة

وإذا لم يتمكن الخادم من فهم طلبك، فإنه يعرض حالة HTTP 400، التي تشير إلى وجود طلب غير صالح. تشمل الأسباب الأكثر شيوعًا للطلب غير الصالح ما يلي:

  • لم يتم تحديد مرجع الصورة الذي تم إرساله بشكل صحيح.
  • لم يتضمّن الطلب المَعلمتَين maxwidth أو maxheight.
  • تم ضبط قيمة المعلَمة maxwidth أو maxheight على null.
  • انتهت صلاحية photo_reference. إذا انتهت صلاحية photo_reference، يمكنك تقديم طلب إلى تفاصيل المكان أو البحث عن مكان أو البحث عن قرب أو البحث النصي للحصول على قيمة photo_reference المعدّلة.