درخواست «تصویر نمای خیابان» یک نشانی وب HTTP در این قالب است:
https://maps.googleapis.com/maps/api/streetview?parameters
تصویر بااستفاده از پارامترهای درخواست مشخص می‌شود. همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه اَند (&) از هم جدا می‌شوند. پارامترهای مجاز و مقادیر احتمالی آن‌ها در زیر فهرست شده است.
پارامترهای الزامی
یکی از موارد زیر را انجام دهید:
locationمی‌تواند رشته نوشتاری (مثلChagrin Falls, OH) یا جفت مختصات طول و عرض جغرافیایی (40.457375,-80.009353) باشد، و باید کدگذاری‌شده با نشانی وب باشد. بنابراین، قبل‌از ارسال درخواست، نشانی‌هایی مانند «City Hall, New York, NY» را به «City+Hall,New+York,NY» تبدیل کنید. Street View Static API به نزدیک‌ترین عکس تمام‌نما به مکان موردنظر می‌پرد. وقتی رشته نوشتاری نشانی را ارائه می‌دهید، ممکن است API از مکان دوربین دیگری استفاده کند تا مکان مشخص‌شده را بهتر نمایش دهد. وقتی مختصات طول و عرض جغرافیایی را ارائه می‌دهید، API در شعاع ۵۰ متری به‌دنبال عکسی می‌گردد که به آن مکان نزدیک‌تر باشد. چون تصاویر «نمای خیابان» به‌طور دوره‌ای بازآوری می‌شود و ممکن است عکس‌ها هر بار از موقعیت‌های کمی متفاوت گرفته شود، ممکن استlocationشما هنگام به‌روزرسانی تصاویر به تمام‌نمای دیگری بچسبد.
یا:
panoشناسه تمام‌نمای خاصی است. ممکن است شناسه سراسرنماها درطول زمان تغییر کند، بنابراین این شناسه را ذخیره نکنید. به‌جای آن، نشانی مکان یا مختصات طول و عرض جغرافیایی را ذخیره کنید تا بتوانید شناسه تمام‌نما را بازآورید. برای جزئیات، به بازآوری شناسه‌های تمام‌نمای حذف‌شده مراجعه کنید.
و همچنین:
-
sizeاندازه خروجی تصویر را به پیکسل مشخص می‌کند. اندازه به‌صورت{width}x{height}مشخص می‌شود - برای مثال،size=600x400تصویری با عرض ۶۰۰ پیکسل و ارتفاع ۴۰۰ پیکسل برمی‌گرداند. keyبه شما امکان می‌دهد استفاده از میانای برنامه‌سازی کاربردی برنامه‌تان را در کنسول Google Cloud پایش کنید، و مطمئن شوید که Google درصورت لزوم می‌تواند درباره برنامه‌تان با شما تماس بگیرد. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.
بازآوری شناسه‌های تمام‌نمای حذف‌شده
اگر تلاش کنید شناسه تمام‌نما را بازیابی کنید و ZERO_RESULTS یا
هیچ مقداری دریافت نکنید، شناسه تمام‌نما حذف شده است و باید بازآوری شود.
نشانی مکان یا مختصات طول و عرض جغرافیایی را که برای دریافت شناسه تمام‌نما استفاده کردید ذخیره کنید تا بتوانید درصورت نیاز بازآوری کنید.
وقتی متوجه شدید که شناسه تمام‌نما تغییر کرده است، از نشانی مکان اصلی یا مختصات طول و عرض جغرافیایی استفاده کنید تا دوباره نزدیک‌ترین تمام‌نماها به آن مکان را جستجو کنید و شناسه تمام‌نمای جدیدی دریافت کنید.
پارامترهای اختیاری
signature(توصیه‌شده) امضای دیجیتالی است که برای تأیید اینکه هر سایتی که بااستفاده از کلید میانای برنامه‌سازی کاربردی شما درخواست تولید می‌کند مجاز به انجام این کار است استفاده می‌شود. درخواست‌هایی که امضای دیجیتالی ندارند ممکن است ناموفق باشند. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.توجه: برای مشتریان سابق «طرح ممتاز Google Maps Platform»، امضای دیجیتال الزامی است. اطلاعات بیشتری درباره پارامترهای اصالت‌سنجی برای مشتریان «طرح Premium» دریافت کنید.
headingنشان‌دهنده جهت قطب‌نمای دوربین است. مقادیر پذیرفتنی از0تا360است (هر دو مقدار نشان‌دهنده شمال،90نشان‌دهنده شرق، و180نشان‌دهنده جنوب است). اگر جهتی را مشخص نکنید، مقداری محاسبه می‌شود که دوربین را از نقطه‌ای که نزدیک‌ترین عکس گرفته شده است به‌سمتlocationمشخص‌شده هدایت می‌کند.fov(پیش‌فرض90است) میدان دید افقی تصویر را برحسب درجه تعیین می‌کند، و حداکثر مقدار مجاز آن120است. هنگام کار با نمای با اندازه ثابت، مانند تصویر «نمای خیابان» با اندازه مشخص، میدان دید در اصل نشان‌دهنده بزرگ‌نمایی است و اعداد کوچک‌تر نشان‌دهنده سطح بزرگ‌نمایی بالاتر هستند.
(چپ:fov=120؛ راست:fov=20)pitch(پیش‌فرض0است) زاویه بالا یا پایین دوربین را نسبت به خودرو «نمای خیابان» مشخص می‌کند. این خط اغلب، اما نه همیشه، افقی و صاف است. مقادیر مثبت زاویه دوربین را به‌سمت بالا می‌برند (90درجه نشان‌دهنده زاویه مستقیم به‌سمت بالا است)؛ مقادیر منفی زاویه دوربین را به‌سمت پایین می‌برند (-90نشان‌دهنده زاویه مستقیم به‌سمت پایین است).radius(پیش‌فرض50است) شعاعی را برحسب متر تنظیم می‌کند که در آن تمام‌نما جستجو شود، و مرکز آن طول و عرض جغرافیایی داده‌شده است. مقادیر معتبر اعداد صحیح غیرمنفی هستند.return_error_codeنشان می‌دهد که آیا API باید کد خطا برگرداند یا نه وقتی تصویری پیدا نشود (خطای ۴۰۴ پیدا نشد)، یا در پاسخ به درخواست نامعتبر (خطای ۴۰۰ درخواست بد). مقادیر معتبرtrueوfalseاست. اگر رویtrueتنظیم شود، پیام خطایی به‌جای تصویر خاکستری عمومی برگردانده می‌شود. این کار نیاز به برقراری تماس جداگانه برای بررسی دردسترس بودن تصویر را ازبین می‌برد.source(پیش‌فرضdefaultاست) جستجوهای «نمای خیابان» را به منابع انتخاب‌شده محدود می‌کند. مقادیر معتبر عبارت‌اند از:defaultاز منابع پیش‌فرض برای «نمای خیابان» استفاده می‌کند؛ جستجوها به منابع خاصی محدود نمی‌شود.outdoorجستجوها را به مجموعه‌های فضای باز محدود می‌کند. مجموعه‌های داخلی در نتایج جستجو گنجانده نمی‌شوند. توجه داشته باشید که ممکن است برای مکان مشخص‌شده، تمام‌نمای فضای باز وجود نداشته باشد. همچنین توجه داشته باشید که جستجو فقط تمام‌نماهایی را برمی‌گرداند که امکان تعیین داخلی یا خارجی بودن آن‌ها وجود داشته باشد. برای مثال، PhotoSpheres برگردانده نمی‌شود چون مشخص نیست که در فضای بسته است یا فضای باز.
این یک درخواست نمونه است.
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
تصویری دردسترس نیست
برای مکان‌هایی که تصاویر «نمای خیابان» دردسترس نیست، Street View Static API تصویر عمومی خاکستری‌رنگی را با نوشتار «متأسفیم، تصویری در اینجا نداریم» برمی‌گرداند، همان‌طور که در این مثال نشان داده شده است:
فقط تصاویر معتبر نشان داده شود
برای جلوگیری از نمایش تصویر عمومی و اطمینان از اینکه صفحه وب شما فقط تصاویر معتبر Street View Static API را نمایش می‌دهد، این پیشنهادها را دنبال کنید:
- پارامتر
return_error_codeرا رویtrueتنظیم کنید. این کار باعث می‌شود که اگر تصویری برای مکان مشخص‌شده دردسترس نباشد، Street View Static API به‌جای تصویر خاکستری عمومی، خطای «۴۰۴ پیدا نشد» را برگرداند. - فراداده تصویر «نمای خیابان» را درخواست کنید تا قبل‌از ارسال درخواست، مشخص شود که آیا تصویری برای مکان مشخص‌شده دردسترس است یا نه.