إن خدمة "صورة المكان" التي تشكّل جزءًا من واجهة برمجة تطبيقات الأماكن هي واجهة برمجة تطبيقات للقراءة فقط تتيح لك إضافة محتوى تصوير فوتوغرافي عالي الجودة إلى تطبيقك. تمنحك خدمة "صورة المكان" إمكانية الوصول إلى ملايين الصور المخزَّنة في قاعدة بيانات "الأماكن". عند الحصول على معلومات عن المكان باستخدام طلب تفاصيل المكان، سيتم عرض مراجع الصور للمحتوى ذي الصلة بالصور. تعرض طلبات "البحث عن المكان" و"البحث عن أماكن قريبة" و"البحث النصي" أيضًا مرجعًا صورة واحدًا لكل مكان، عندما يكون ذلك مناسبًا. باستخدام خدمة الصور يمكنك الوصول إلى الصور المُشار إليها وتغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.
طلبات صور المكان
طلب صورة المكان هو عنوان 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.
Optional parameters
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. Both the
maxheight
andmaxwidth
properties accept an integer between1
and1600
.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
.
Generated from the OpenAPI specification. Edit Report bug
مراجع الصور
يجب أن تشمل جميع الطلبات الموجّهة إلى خدمة "صور الأماكن" photoreference
مع عرض الردّ على طلب "البحث عن مكان" أو "البحث عن الأماكن المجاورة" أو "بحث نصي" أو "تفاصيل المكان". ستتضمّن الاستجابة لهذه الطلبات حقل photos[]
إذا
كان المكان يعرض صورًا فوتوغرافية ذات صلة.
ملاحظة: يختلف عدد الصور التي يتم عرضها حسب الطلب.
- يعرض طلب "العثور على مكان" أو "بحث مجاور" أو "بحث نصي" عنصرًا واحدًا
photo
واحد على الأكثر في المصفوفة. - يعرض طلب تفاصيل المكان ما يصل إلى عشرة عناصر
photo
.
سيحتوي كل عنصر photo
على الحقول التالية:
photo_reference
: سلسلة يتم استخدامها لتحديد الصورة عند تنفيذ طلب صورة.height
: أقصى ارتفاع للصورة.width
: الحد الأقصى لعرض الصورة.html_attributions[]
: يحتوي على أي إحالات مطلوبة. وسيظل هذا الحقل معروضًا دائمًا، ولكنه قد يكون فارغًا.
يتم الحصول على الصور التي تعرضها خدمة "صور Google" من مجموعة متنوعة من المواقع الجغرافية، بما في ذلك مالكو الأنشطة التجارية والصور التي يساهم بها المستخدمون. وفي معظم الحالات، يمكن استخدام هذه الصور بدون إحالة أو سيتم تضمين الإحالة المطلوبة كجزء من الصورة. أما إذا كان العنصر photo
المعروض
يحتوي على قيمة في الحقل html_attributions
، فيجب تضمين
الإحالة الإضافية في تطبيقك حيثما تعرض الصورة.
وفي ما يلي مثال على مصفوفة photos[]
.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "CnRvAAAAwMpdHeWlXl-lH0vp7lez4znKPIWSWvgvZFISdKx45AwJVP1Qp37YOrH7sqHMJ8C-vBDC546decipPHchJhHZL94RcTUfPa1jWzo-rSHaTlbNtjh-N68RkcToUCuY9v2HNpo5mziqkir37WU8FJEqVBIQ4k938TI3e7bf8xq-uwDZcxoUbO_ZJzPxremiQurAYzCTwRhE_V0"
}
...
مثال على صورة المكان
وفي ما يلي مثال على الطلب. سيؤدي هذا الطلب إلى عرض الصورة المُشار إليها، مع تغيير حجمها بحيث لا يزيد عرضها عن 400 بكسل.
https://maps.googleapis.com/maps/api/place/photo ?maxwidth=400 &photo_reference=Aap_uEA7vb0DDYVJWEaX3O-AtYp77AaswQKSGtDaimt3gt7QCNpdjp1BkdM6acJ96xTec3tsV_ZJNL_JP-lqsVxydG3nh739RE_hepOOL05tfJh2_ranjMadb3VoBYFvF0ma6S24qZ6QJUuV6sSRrhCskSBP5C1myCzsebztMfGvm7ij3gZT &key=YOUR_API_KEY
الرد على صورة المكان
ستكون الاستجابة لطلب صورة مكان ناجح صورة. يعتمد نوع الصورة على نوع الصورة التي تم إرسالها في الأصل.
إذا تجاوز طلبك الحصة المتوفرة، سيعرض الخادم حالة HTTP 403 ويعرض الصورة التالية للإشارة إلى أنه تم تجاوز الحصة:
إذا لم يتمكّن الخادم من فهم طلبك، سيؤدي إلى عرض حالة HTTP 400 التي تشير إلى طلب غير صالح. تشمل الأسباب الأكثر شيوعًا للطلب غير الصالح ما يلي:
- لم يتم تحديد مرجع الصورة الذي تم إرساله بشكل صحيح.
- لم يتضمّن الطلب المَعلمتَين
maxwidth
أوmaxheight
. - تم ضبط قيمة المَعلمة
maxwidth
أو المَعلمةmaxheight
علىnull
.