صور المكان

اختَر النظام الأساسي: 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 المعدّلة.