صور المكان

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

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

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

طلب صورة مكان هو عنوان 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[]: يحتوي على أيّ إحالات ضرورية. سيكون هذا الحقل متوفّرًا دائمًا، ولكن قد يكون فارغًا.

يتم الحصول على الصور التي تعرضها خدمة "صور Google" من مجموعة متنوعة من المواقع الجغرافية، بما في ذلك الصور التي ينشرها مالكو الأنشطة التجارية والمستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون نسبها إلى مصدرها، أو سيتم تضمين الإسناد المطلوب كجزء من الصورة. ومع ذلك، إذا كان عنصر 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 ، ما يشير إلى أنّ الطلب غير صالح. تشمل الأسباب الأكثر شيوعًا لتلقّي طلب غير صالح ما يلي: