Place Photos (Legacy)، بخشی از Places API، یک API فقط خواندنی است که به شما امکان می‌دهد محتوای عکاسی با کیفیت بالا را به برنامه خود اضافه کنید. Place Photos (Legacy) به شما امکان می‌دهد به میلیون‌ها عکس ذخیره‌شده در پایگاه داده Places دسترسی داشته باشید. وقتی اطلاعات مکانی را بااستفاده از درخواست «جزئیات جا» دریافت می‌کنید، ارجاع‌های عکس برای محتوای عکاسی مربوطه برگردانده می‌شود. درخواست‌های «یافتن مکان» (قدیمی)، «جستجوی اطراف» (قدیمی)، و «جستجوی نوشتار» (قدیمی) نیز درصورت مرتبط بودن، یک مرجع عکس برای هر مکان برمی‌گردانند. بااستفاده از Place Photos (Legacy) می‌توانید به عکس‌های ارجاع‌شده دسترسی پیدا کنید و اندازه تصویر را به اندازه بهینه برای برنامه‌تان تغییر دهید.
درخواست‌های Place Photos (Legacy)
درخواست Place Photos (Legacy) یک نشانی وب HTTP به شکل زیر است:
https://maps.googleapis.com/maps/api/place/photo?parameters
پارامترهای خاصی برای شروع درخواست جستجو لازم است. همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه اَمپرسند (&) از هم جدا می‌شوند. فهرست
پارامترها و مقادیر احتمالی آن‌ها در زیر ذکر شده است.
پارامترهای الزامی
-
photo_reference
شناسه رشته‌ای که عکس را به‌طور یکتا شناسایی می‌کند. ارجاع‌های عکس از درخواست «جستجوی جاها» یا «جزئیات جا» برگردانده می‌شود.
-
maxheight یا maxwidth
maxheightحداکثر ارتفاع ترجیحی تصویر را به پیکسل مشخص می‌کند. اگر تصویر کوچک‌تر از مقادیر مشخص‌شده باشد، تصویر اصلی برگردانده خواهد شد. اگر تصویر در هریک از ابعاد بزرگ‌تر باشد، مقیاس آن تغییر می‌کند تا با بعد کوچک‌تر مطابقت داشته باشد و به نسبت ابعادی اصلی‌اش محدود می‌شود.maxwidthحداکثر عرض ترجیحی تصویر را به پیکسل مشخص می‌کند. اگر تصویر کوچک‌تر از مقادیر مشخص‌شده باشد، تصویر اصلی برگردانده خواهد شد. اگر تصویر در هریک از ابعاد بزرگ‌تر باشد، مقیاس آن تغییر می‌کند تا با بعد کوچک‌تر مطابقت داشته باشد و به نسبت ابعادی اصلی‌اش محدود می‌شود.هر دو ویژگی
maxheightوmaxwidthعدد صحیحی بین1و1600را می‌پذیرند.باید
maxheightیاmaxwidthیا هر دو را مشخص کنید.
مرجع عکس
همه درخواست‌ها به Place Photos (قدیمی) باید شامل photo_reference باشد،
که در پاسخ به درخواست «یافتن مکان» (قدیمی)، «جستجوی اطراف» (قدیمی)،
«جستجوی نوشتار» (قدیمی)، یا «جزئیات مکان» (قدیمی) برگردانده می‌شود. اگر مکان محتوای عکاسی مرتبط داشته باشد، پاسخ به این درخواست‌ها حاوی فیلد photos[] خواهد بود.
توجه: تعداد عکس‌های برگردانده‌شده بسته به درخواست متفاوت است.
- درخواست «یافتن مکان» (قدیمی)، «جستجوی اطراف» (قدیمی)، یا «جستجوی نوشتار» (قدیمی)
حداکثر یک عنصر
photoدر آرایه برمی‌گرداند. - درخواست «جزئیات مکان (قدیمی)» حداکثر ده عنصر
photoرا برمی‌گرداند.
هر عنصر photo حاوی فیلدهای زیر است:
photo_reference— رشته‌ای که برای شناسایی عکس هنگام اجرای درخواست «عکس‌های مکان» (قدیمی) استفاده می‌شود.height— حداکثر ارتفاع تصویر.width— حداکثر عرض تصویر.-
html_attributions[]— حاوی هرگونه ارجاع لازم است. این فیلد همیشه وجود خواهد داشت، اما ممکن است خالی باشد.
عکس‌هایی که Place Photos (Legacy) برمی‌گرداند از مکان‌های مختلفی گرفته شده‌اند،
ازجمله عکس‌های ارائه‌شده توسط مالکان کسب‌وکار و کاربران. در بیشتر موارد، این عکس‌ها را می‌توان بدون ارجاع استفاده کرد، یا ارجاع لازم به‌عنوان بخشی از تصویر گنجانده شده است. بااین‌حال، اگر عنصر photo برگردانده‌شده
شامل مقداری در فیلد html_attributions باشد، باید
ارجاع اضافی را در هر جایی از برنامه‌تان که تصویر را نمایش می‌دهید بگنجانید.
نمونه زیر درخواست «جزئیات مکان (قدیمی)» را نشان می‌دهد:
curl "https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJcUElzOzMQQwRLuV30nMUEUM&key=YOUR_API_KEY"
نمونه‌ای از آرایه photos[] در پاسخ در زیر نشان داده شده است.
...
"photos" : [
{
"html_attributions" : [],
"height" : 853,
"width" : 1280,
"photo_reference" : "ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q"
}]
...
نمونه Place Photos (Legacy)
درخواست نمونه‌ای در زیر نشان داده شده است. این درخواست تصویر ارجاع‌شده را برمی‌گرداند و اندازه آن را تغییر می‌دهد تا حداکثر ۴۰۰ پیکسل عرض داشته باشد.
https://maps.googleapis.com/maps/api/place/photo?maxwidth=400&photo_reference=ATJ83zhSSAtkh5LTozXMhBghqubeOxnZWUV2m7Hv2tQaIzKQJgvZk9yCaEjBW0r0Zx1oJ9RF1G7oeM34sQQMOv8s2zA0sgGBiyBgvdyMxeVByRgHUXmv-rkJ2wyvNv17jyTSySm_-_6R2B0v4eKX257HOxvXlx_TSwp2NrICKrZM2d5d2P4q &key=YOUR_API_KEY
پاسخ Place Photos (Legacy)
پاسخ درخواست موفق Place Photos (Legacy) یک تصویر است. نوع تصویر به نوع عکس ارسال‌شده اصلی بستگی دارد.
اگر درخواست شما از سهمیه دردسترس شما فراتر رود، سرور وضعیت HTTP 403 را برمی‌گرداند و تصویر زیر را نمایش می‌دهد تا نشان دهد که سهمیه فراتر رفته است:
اگر سرور نتواند درخواست شما را درک کند، وضعیت HTTP 400 را برمی‌گرداند که نشان‌دهنده درخواست نامعتبر است. رایج‌ترین دلایل درخواست نامعتبر عبارت‌اند از:
- مرجع عکس ارسال‌شده به‌درستی مشخص نشده بود.
- درخواست شامل پارامترهای
maxwidthیاmaxheightنبود. - مقدار پارامتر
maxwidthیاmaxheightرویnullتنظیم شده است. photo_referenceمنقضی شده است. اگرphoto_referenceمنقضی شد، درخواستی به جزئیات جا (قدیمی)، یافتن جا (قدیمی)، جستجوی اطراف (قدیمی)، یا جستجوی نوشتار (قدیمی) ارسال کنید تا مقدارphoto_referenceبه‌روزشده را دریافت کنید.