صور المكان

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

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

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

طلب صورة المكان هو عنوان 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 and maxwidth properties accept an integer between 1 and 1600.

  • 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.

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.