خدمة 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
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
.