خدمة 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[]
— أي سمات مطلوبة يكون هذا الحقل متوفرًا دائمًا، ولكنه قد يكون فارغًا.
يتم الحصول على الصور التي تعرضها خدمة الصور من مجموعة متنوعة من المواقع، بما في ذلك مالكي الأنشطة التجارية والصور التي يساهم بها المستخدمون. في معظم الحالات، يمكن استخدام هذه الصور بدون نَسب العمل، أو سيتم تضمين الإسناد المطلوب كجزء من الصورة. وإذا كان عنصر 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. يعرض الطلب تلقائيًا الصورة التي لا يمكن عرضها بواسطة مستكشف واجهة برمجة التطبيقات. - انقر على الزر تنفيذ. في النافذة المنبثقة، اختَر الحساب الذي تريد استخدامه لتقديم الطلب.
في لوحة "مستكشف واجهات برمجة التطبيقات"، انقر على رمز التوسيع، ، لتوسيع نافذة "مستكشف واجهة برمجة التطبيقات".