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

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

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

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

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

جرِّبه الآن

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

طلب "صورة مكان" هو طلب 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.

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

يجب أن تشتمل جميع الطلبات المقدّمة لخدمة "صور المكان" على اسم لمورد صور يتم عرضه استجابةً لطلب بحث عن مكان قريب أو بحث نصي أو تفاصيل مكان. يحتوي الردّ على هذه الطلبات على مصفوفة photos[] إذا كان الموقع يحتوي على محتوى صوري ذي صلة.

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

  • name: سلسلة تحتوي على اسم مورد الصورة عند تنفيذ طلب صور تكون هذه السلسلة بالشكل التالي:

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

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

يعرض المثال التالي طلب "تفاصيل المكان" يتضمّن 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/AUacShh3_Dd8yvV2JZMtNjjbbSbFhSv-0VmUN-uasQ2Oj00XB63irPTks0-A_1rMNfdTunoOVZfVOExRRBNrupUf8TY4Kw5iQNQgf2rwcaM8hXNQg7KDyvMR5B-HzoCE1mwy2ba9yxvmtiJrdV-xBgO8c5iJL65BCd0slyI1/media?maxHeightPx=400&maxWidthPx=400&key=API_KEY

الاستجابة لطلب صورة مكان ناجح هي صورة. يعتمد نوع الصورة على نوع الصورة التي تم إرسالها في الأصل.

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

صورة تم تجاوز الحصة المحدّدة

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

جرّب الآن

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

لتقديم طلب:

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

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