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