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

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

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

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

جرِّبه الآن

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

طلب "صورة مكان" هو طلب 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 ، ما يشير إلى أنّ الطلب غير صالح. تشمل الأسباب الأكثر شيوعًا لتلقّي طلب غير صالح ما يلي:

• لم يتم تحديد اسم الصورة المرسَلة بشكل صحيح.
• لم يتضمّن الطلب المَعلمة maxHeightPx أو maxWidthPx
• تم ضبط قيمة المَعلمة maxHeightPx أو maxWidthtPx على null.
• انتهت صلاحية name. إذا انتهت صلاحية name، قدِّم طلبًا إلى تفاصيل الأماكن (ميزة جديدة) أو البحث عن الأماكن المجاورة (ميزة جديدة) أو البحث النصي (ميزة جديدة) للحصول على name جديد.

جرّب الآن

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

لتقديم طلب:

1. انقر على رمز واجهة برمجة التطبيقات على يسار الصفحة.
2. اضبط المَعلمة name على:

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

3. اضبط skipHttpRedirect على true لكي يعرض الطلب استجابة بتنسيق JSON. يعرض الطلب تلقائيًا الصورة التي لا يمكن عرضها من خلال "مستكشف واجهة برمجة التطبيقات".
4. انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.

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