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

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

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

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

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

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

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

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

يتم الحصول على الصور التي تعرضها ميزة "صور الأماكن (جديد)" من مجموعة متنوعة من المواقع الجغرافية، بما في ذلك الصور التي ينشرها مالكو الأنشطة التجارية والمستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون نسبها إلى مصدرها، أو سيتم تضمين الإسناد المطلوب كجزء من الصورة. ومع ذلك، إذا كان عنصر 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. انقر على رمز واجهة برمجة التطبيقات api على يسار الصفحة.
  2. اضبط المَعلمة name على: 
    places/PLACE_ID/photos/PHOTO_RESOURCE/media
  3. اضبط skipHttpRedirect على true لكي يعرض الطلب استجابة بتنسيق JSON. يعرض الطلب تلقائيًا الصورة التي لا يمكن عرضها من خلال "مستكشف واجهة برمجة التطبيقات".
  4. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

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