صورة المكان (جديدة) هي واجهة برمجة تطبيقات للقراءة فقط تتيح لك إضافة عناصر الصور الفوتوغرافية إلى تطبيقك. تمنحك خدمة "صور الأماكن" يمكنك الوصول إلى ملايين الصور المخزنة في قاعدة بيانات الأماكن.
عندما تحصل على معلومات عن مكان من خلال تفاصيل المكان أو البحث عن قرب أو طلب البحث النصي، يمكنك أيضًا طلب موارد صور لمحتوى فوتوغرافي ذي صلة. باستخدام خدمة الصور، يمكنك بعد ذلك الوصول إلى الصور المرجعية وتغيير حجم الصورة إلى الحجم الأمثل التطبيق.
تتيح لك مستكشف واجهات برمجة التطبيقات إجراء طلبات مباشرة حتى تتمكن من التعرّف على واجهة برمجة التطبيقات خيارات واجهة برمجة التطبيقات:
جرِّبه الآنطلبات صور الأماكن
طلب "صورة المكان" هو طلب 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 وعرض الصورة أدناه للإشارة إلى أن الحصة تم تجاوز:
![صورة تم تجاوز الحصة المحدّدة](https://developers.google.cn/static/maps/documentation/maps-static/images/quota.png?authuser=5&hl=ar)
إذا لم يتمكن الخادم من فهم طلبك، فإنه يعرض HTTP 400 الحالة، مما يشير إلى طلب غير صالح. تشمل الأسباب الأكثر شيوعًا الطلب غير الصالح:
- لم يتم تحديد اسم الصورة الذي تم إرساله بشكل صحيح.
- لم يتضمّن الطلب
maxHeightPx
أوmaxWidthPx
. . - تم ضبط قيمة المعلَمة
maxHeightPx
أوmaxWidthtPx
. إلىnull
. - انتهت صلاحية
name
. في حال انتهاء صلاحية "name
"، يمكنك إنشاء طلب إلى تفاصيل المكان (جديد)، البحث عن قرب (جديد)، أو البحث النصي (جديد) للحصول علىname
جديدة.
جرّب الآن
يتيح لك "مستكشف واجهات برمجة التطبيقات" تقديم طلبات نموذجية حتى تتمكن من الإلمام بخيارات واجهة برمجة التطبيقات وواجهة برمجة التطبيقات.
لتقديم طلب:
- انقر على رمز واجهة برمجة التطبيقات،
، على الجانب الأيمن من الصفحة.
- اضبط المَعلمة
name
على:places/PLACE_ID/photos/PHOTO_RESOURCE/media
- يجب ضبط السمة
skipHttpRedirect
علىtrue
لكي يعرض الطلب ملف JSON الاستجابة. يعرض الطلب بشكل افتراضي الصورة التي لا يمكن عرضها بواسطة مستكشف واجهات برمجة التطبيقات. - انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه. استخدامها لتقديم الطلب.
في لوحة "مستكشف واجهة برمجة التطبيقات"، حدد رمز التوسيع،
، لتوسيع نافذة مستكشف واجهة برمجة التطبيقات