صور المكان (جديدة)

اختيار المنصة: Android iOS Web Service
لمطوّري التطبيقات المقيمين في المنطقة الاقتصادية الأوروبية (EEA)

مقدمة

خدمة صور الأماكن (جديد) هي واجهة برمجة تطبيقات للقراءة فقط تتيح لك إضافة محتوى فوتوغرافي عالي الجودة إلى تطبيقك. تمنحك خدمة Place Photos (New) إمكانية الوصول إلى ملايين الصور المخزّنة في قاعدة بيانات "الأماكن".

عند الحصول على معلومات عن مكان باستخدام طلب تفاصيل المكان (جديد) أو بحث في الجوار (جديد) أو البحث النصي (جديد)، يمكنك أيضًا طلب موارد الصور للحصول على محتوى فوتوغرافي ذي صلة. باستخدام صور الأماكن (جديد)، يمكنك بعد ذلك الوصول إلى الصور المرجعية وتغيير حجم الـ صورة إلى الحجم الأمثل لتطبيقك.

يتيح لك مستكشف واجهات برمجة التطبيقات إرسال طلبات مباشرة لتتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها:

طلبات Place Photos (New)

طلب Place Photos (New) هو طلب HTTP GET إلى عنوان URL بالتنسيق التالي: 
https://places.googleapis.com/v1/NAME/media?key=API_KEY&PARAMETERS

المعلمات التالية مطلوبة:

  • يحتوي NAME على اسم مورد الصورة.
  • يحتوي API_KEY على مفتاح واجهة برمجة التطبيقات.
  • PARAMETERS يحتوي على المعلمة maxHeightPx أو المعلمة maxWidthPx أو كلتيهما.

في ما يلي وصف للقائمة الكاملة من المعلمات المطلوبة والاختيارية.

المعلمات المطلوبة

اسم الصورة

معرّف سلسلة يحدّد صورة بشكل فريد. يتم عرض أسماء الصور من طلب تفاصيل المكان (جديد) أو بحث في الجوار (جديد) أو البحث النصي (جديد) في السمة name لكل عنصر من عناصر المصفوفة photos[].

للاطّلاع على مثال، يُرجى الانتقال إلى الحصول على اسم صورة.

maxHeightPx وmaxWidthPx

تحدّد هذه المعلمة الحد الأقصى للارتفاع والعرض المطلوبَين للصورة بالبكسل. إذا كانت الصورة أصغر من القيم المحدّدة، سيتم عرض الصورة الأصلية. إذا كانت الصورة أكبر في أي من البُعدَين، سيتم تغيير حجمها ليطابق البُعد الأصغر من البُعدَين، مع الحفاظ على نسبة العرض إلى الارتفاع الأصلية. تقبل كلٌّ من السمتَين maxheight وmaxwidth عددًا صحيحًا يتراوح بين 1 و4800.

يجب تحديد maxHeightPx أو maxWidthPx أو كلتيهما.

المعلمات الاختيارية

skipHttpRedirect

إذا كانت القيمة false (القيمة التلقائية)، يتم إجراء عملية إعادة توجيه HTTP إلى الصورة لعرضها. إذا كانت القيمة true، يتم تخطّي عملية إعادة التوجيه وعرض استجابة JSON تحتوي على تفاصيل الصورة. على سبيل المثال:

{
  "name": "places/ChIJj61dQgK6j4AR4GeTYWZsKWw/photos/Aaw_FcKly0DEv3EWmDJyHiEqXIP5mowOc99lN1GzBun6KHH52AZ5fFA/media",
  "photoUri": "https://lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
}

يتم تجاهل هذا الخيار للطلبات غير المستندة إلى HTTP.

الحصول على اسم صورة

يجب أن تتضمّن جميع الطلبات إلى صور الأماكن (New) اسم مورد صورة ، يتم عرضه في الاستجابة لطلب بحث في الجوار (New) أو البحث النصي (New) أو تفاصيل المكان (New). تحتوي الاستجابة لهذه الطلبات على مصفوفة photos[] إذا كان للمكان محتوى فوتوغرافي ذو صلة.

يحتوي كل عنصر من عناصر photo[] على الحقول التالية:

  • name : سلسلة تحتوي على اسم مورد الصورة عند إجراء طلب صورة. تكون هذه السلسلة بالتنسيق التالي:

    places/PLACE_ID/photos/PHOTO_RESOURCE
  • heightPx : الحد الأقصى لارتفاع الصورة بالبكسل.
  • widthPx : الحد الأقصى لعرض الصورة بالبكسل.
  • authorAttributions[] : أي عمليات إسناد مطلوبة. هذا الحقل موجود دائمًا، ولكن قد يكون فارغًا.

يتم الحصول على الصور التي تعرضها Place Photos (New) من مجموعة متنوعة من المواقع الجغرافية، بما في ذلك الصور التي يقدّمها مالكو الأنشطة التجارية والمستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون إسنادها إلى مؤلفها، أو سيتم تضمين عملية الإسناد المطلوبة كجزء من الصورة. ومع ذلك، إذا كان عنصر photo المعروض يتضمّن قيمة في الحقل authorAttributions، يجب تضمين عملية الإسناد الإضافية في تطبيقك أينما تعرض الصورة.

يعرض المثال التالي طلب تفاصيل المكان (New) يتضمّن photos في قناع الحقول لكي تتضمّن الاستجابة مصفوفة photos[]

curl -X GET \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,photos" \
https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E
 في ما يلي مثال على مصفوفة photos[] في الاستجابة. 
    ...
    "photos" : [
      {
        "name": "places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1",
        "widthPx": 6000,
        "heightPx": 4000,
        "authorAttributions": [
          {
            "displayName": "John Smith",
            "uri": "//maps.google.com/maps/contrib/101563",
            "photoUri": "//lh3.googleusercontent.com/a-/AD_cFT-b=s100-p-k-no-mo"
          }
        ]
      },
    ...

طلب صورة مكان

يعرض طلب المثال أدناه صورة باستخدام name المورد الخاص بها، مع تغيير حجمها بحيث لا يزيد ارتفاعها وعرضها عن 400 بكسل:

https://places.googleapis.com/v1/places/ChIJ2fzCmcW7j4AR2JzfXBBoh6E/photos/ATKogpeivkIjQ1FT7QmbeT33nBSwqLhdPvIWHfrG1WfmgrFjeZYpS_Ls7c7rj8jejN9QGzlx4GoAH0atSvUzATDrgrZic_tTEJdeITdWL-oG3TWi5HqZoLozrjTaxoAIxmROHfV5KXVcLeTdCC6kmZExSy0CLVIG3lAPIgmvUiewNf-ZHYE4-jXYwPQpWHJgqVosvZJ6KWEgowEA-qRAzNTu9VH6BPFqHakGQ7EqBAeYOiU8Dh-xIQC8FcBJiTi0xB4tr-MYXUaF0p_AqzAhJcDE6FAgLqG1s7EsME0o36w2nDRHA-IuoISBC3SIahINE3Xwq2FzEZE6TpNTFVfgTpdPhV8CGLeqrauHn2I6ePm-2hA8-87aO7aClXKJJVzlQ1dc_JuHz6Ks07d2gglw-ZQ3ibCTF5lMtCF9O-9JHyRQXsfuXw/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

الـ استجابة لطلب صور الأماكن (جديد) الناجح هي صورة.

رموز الخطأ

قد تعرض طلبات صور الأماكن (الجديدة) رموز الخطأ التالية.

تم تجاوز الحصة (403)

إذا تجاوز طلبك الحصة المتاحة لك، يعرض الخادم حالة HTTP 403 ويعرض الصورة التالية للإشارة إلى أنّه تم تجاوز الحصة:

إشعار بتجاوز الحصة المخصّصة

طلب غير صالح (404)

إذا تعذّر على الخادم فهم طلبك، يعرض حالة HTTP 400، ما يشير إلى أنّ الطلب غير صالح. تشمل الأسباب الأكثر شيوعًا للطلب غير الصالح ما يلي:

عدد كبير من الطلبات (429)

تنصح Google بتحميل الصور عند الطلب. إذا حاولت عرض جميع صور مكان في وقت واحد، قد يعرض الخادم حالة HTTP 429 تشير إلى أنّه يتم تحميل عدد كبير جدًا من الصور في الوقت نفسه. إذا ظهرت لك رسالة الخطأ هذه، تواصَل مع فريق الدعم واطلب زيادة الحصة.

جرِّبه الآن

يتيح لك مستكشف واجهات برمجة التطبيقات إرسال طلبات نموذجية لتتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

لإرسال طلب:

  1. انقر على رمز واجهة برمجة التطبيقات على الجانب الأيسر من الصفحة.
  2. اضبط المعلمة name على: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. اضبط skipHttpRedirect على true لكي يعرض الطلب استجابة JSON. يعرض الطلب الصورة تلقائيًا، ولا يمكن لمستكشف واجهات برمجة التطبيقات عرضها.
  4. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لإرسال الطلب.

  5. في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز ملء الشاشة لتوسيع نافذة "مستكشف واجهات برمجة التطبيقات" .