تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

اختَر النظام الأساسي: 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[] إذا كان المكان يتضمّن محتوًى فوتوغرافيًا ذي صلة.

ملاحظة: لتضمين مصفوفة photos[] في الرد، احرص على تضمين photos (تفاصيل المكان) أو places.photos (البحث عن قرب والبحث النصي) في قناع حقل الطلب. ويمكن لكل واجهة برمجة تطبيقات أن تعرض ما يصل إلى 10 صور لموقع جغرافي محدّد.

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

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

تجربة

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

لتقديم طلب:

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