صور المكان

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

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

تقديم طلبات الصور

طلب صورة المكان هو عنوان 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.