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

مقدمة

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

عند الحصول على معلومات عن مكان باستخدام طلب Place Details (New) أو Nearby Search (New) أو Text Search (New)، يمكنك أيضًا طلب مراجع صور للحصول على محتوى فوتوغرافي ذي صلة. باستخدام Place Photos (New)، يمكنك بعد ذلك الوصول إلى الصور المشار إليها وتغيير حجم الصورة إلى الحجم الأمثل لتطبيقك.

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

طلبات "صور المكان" (جديدة)

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.

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

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

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

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

  places/PLACE_ID/photos/PHOTO_RESOURCE

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

يتم الحصول على الصور التي تعرضها خدمة Place Photos (New) من مجموعة متنوعة من المصادر، بما في ذلك مالكو الأنشطة التجارية والصور التي يساهم بها المستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون الإشارة إلى المصدر، أو سيتم تضمين الإشارة المطلوبة إلى المصدر كجزء من الصورة. ومع ذلك، إذا كان العنصر 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" : [
      {
        "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

الرد على طلب ناجح بشأن "صور الأماكن (الجديدة)" هو صورة.

رموز الخطأ

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

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

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

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

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

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

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

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

جرِّبها الآن

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

لتقديم طلب، اتّبِع الخطوات التالية:

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

   places/PLACE_ID/photos/PHOTO_RESOURCE/media

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

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