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

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

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

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

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

جرِّبه الآن

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

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

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