تُعد خدمة 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
andmaxwidth
properties accept an integer between1
and1600
.You must specify either
maxheight
, ormaxwidth
, 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
المعدّلة.