درخواست تصویر نمای خیابان، یک URL HTTP با این قالب است:
https://maps.googleapis.com/maps/api/streetview?parameters
تصویر با استفاده از پارامترهای درخواست مشخص می‌شود. همانطور که در URLها استاندارد است، تمام پارامترها با استفاده از کاراکتر آمپرسند (&) از هم جدا می‌شوند. پارامترهای مجاز و مقادیر ممکن آنها در زیر فهرست شده‌اند.
پارامترهای مورد نیاز
یا:
-
locationمی‌تواند یک رشته متنی (مانندChagrin Falls, OH) یا یک جفت مختصات طول و عرض جغرافیایی (40.457375,-80.009353) باشد و باید به صورت URL کدگذاری شود . بنابراین، قبل از ارسال درخواست، آدرس‌هایی مانند "City Hall، New York، NY" را به "City+Hall، New+York، NY" تبدیل کنید. API نمای خیابان استاتیک، عکس پانورامای نزدیک به مکان را نمایش می‌دهد. وقتی یک رشته متن آدرس ارائه می‌دهید، API ممکن است از مکان دوربین متفاوتی برای نمایش بهتر مکان مشخص شده استفاده کند. وقتی مختصات طول و عرض جغرافیایی را ارائه می‌دهید، API شعاع 50 متری را برای یافتن عکسی نزدیک به مکان جستجو می‌کند. از آنجا که تصاویر نمای خیابان به صورت دوره‌ای به‌روزرسانی می‌شوند و عکس‌ها ممکن است هر بار از موقعیت‌های کمی متفاوت گرفته شوند، این امکان وجود دارد کهlocationشما هنگام به‌روزرسانی تصاویر، به یک پانورامای متفاوت تبدیل شود.
یا:
-
panoیک شناسه خاص پانوراما است. پانوراماها ممکن است شناسه خود را به مرور زمان تغییر دهند، بنابراین این شناسه را حفظ نکنید. در عوض، آدرس مکان یا مختصات طول و عرض جغرافیایی را ذخیره کنید تا بتوانید شناسه پانوراما را به‌روزرسانی کنید. برای جزئیات بیشتر، به «به‌روزرسانی شناسه‌های پانورامای حذف‌شده» مراجعه کنید.
و همچنین:
-
sizeاندازه خروجی تصویر را بر حسب پیکسل مشخص می‌کند. Size به صورت{width}x{height}مشخص می‌شود - برای مثال،size=600x400تصویری با عرض ۶۰۰ پیکسل و ارتفاع ۴۰۰ پیکسل را برمی‌گرداند. -
keyبه شما امکان می‌دهد میزان استفاده از API برنامه خود را در کنسول Google Cloud رصد کنید و تضمین می‌کند که گوگل در صورت لزوم می‌تواند در مورد برنامه شما با شما تماس بگیرد. برای اطلاعات بیشتر، به «دریافت کلید و امضا» مراجعه کنید.
شناسه‌های پانورامای حذف‌شده را به‌روزرسانی کنید
اگر سعی در بازیابی شناسه پانوراما دارید و مقدار ZERO_RESULTS یا هیچ مقداری دریافت نمی‌کنید، شناسه پانوراما حذف شده است و نیاز به به‌روزرسانی دارد.
آدرس مکان یا مختصات طول و عرض جغرافیایی که برای دریافت شناسه پانوراما استفاده کرده‌اید را ذخیره کنید تا در صورت نیاز بتوانید آن را به‌روزرسانی کنید.
وقتی متوجه شدید که شناسه پانوراما تغییر کرده است، از آدرس مکان اصلی یا مختصات طول و عرض جغرافیایی برای جستجوی مجدد نزدیکترین پانوراماها به آن مکان استفاده کنید و یک شناسه پانورامای جدید دریافت کنید.
پارامترهای اختیاری
-
signature( توصیه می‌شود ) یک امضای دیجیتالی است که برای تأیید اینکه هر سایتی که با استفاده از کلید API شما درخواست ایجاد می‌کند، مجاز به انجام این کار است، استفاده می‌شود. درخواست‌هایی که شامل امضای دیجیتالی نباشند ممکن است با شکست مواجه شوند. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.توجه: برای مشتریان سابق طرح ویژه پلتفرم نقشه‌های گوگل، امضای دیجیتال الزامی است . اطلاعات بیشتری در مورد پارامترهای احراز هویت برای مشتریان طرح ویژه دریافت کنید.
-
headingجهت قطب‌نمای دوربین را نشان می‌دهد. مقادیر پذیرفته شده از0تا360هستند (هر دو مقدار نشان دهنده شمال،90نشان دهنده شرق و180جنوب هستند). اگر عنوانی مشخص نکنید، مقداری محاسبه می‌شود که دوربین را به سمتlocationمشخص شده، از نقطه‌ای که نزدیکترین عکس گرفته شده است، هدایت می‌کند. -
fov(مقدار پیش‌فرض90است ) میدان دید افقی تصویر را که بر حسب درجه بیان می‌شود، با حداکثر مقدار مجاز120تعیین می‌کند. هنگام کار با یک نمای ثابت، مانند تصویر Street View با اندازه مشخص، میدان دید در اصل نشان‌دهنده بزرگنمایی است و اعداد کوچکتر نشان‌دهنده سطح بالاتر بزرگنمایی هستند.
(چپ:fov=120; راست:fov=20) -
pitch( پیش‌فرض0است) زاویه دوربین را نسبت به وسیله نقلیه نمای خیابان به سمت بالا یا پایین مشخص می‌کند. این زاویه اغلب، اما نه همیشه، افقی و مسطح است. مقادیر مثبت، زاویه دوربین را به سمت بالا (90درجه نشان‌دهنده جهت مستقیم رو به بالا) و مقادیر منفی، زاویه دوربین را به سمت پایین (-90درجه نشان‌دهنده جهت مستقیم رو به پایین) تنظیم می‌کنند. -
radius( پیش‌فرض50است) شعاعی را بر حسب متر تعیین می‌کند که در آن می‌توان یک پانوراما را با محوریت طول و عرض جغرافیایی داده شده جستجو کرد. مقادیر معتبر، اعداد صحیح غیر منفی هستند. -
return_error_codeنشان می‌دهد که آیا API باید در صورت عدم یافتن تصویر (404 NOT FOUND) یا در پاسخ به یک درخواست نامعتبر (400 BAD REQUEST) کد خطا را برگرداند. مقادیر معتبرtrueوfalseهستند. اگر رویtrueتنظیم شود، یک پیام خطا به جای تصویر خاکستری عمومی برگردانده می‌شود. این امر نیاز به ایجاد یک فراخوانی جداگانه برای بررسی در دسترس بودن تصویر را از بین می‌برد. -
source( پیش‌فرضdefaultاست) جستجوهای نمای خیابان را به منابع انتخاب‌شده محدود می‌کند. مقادیر معتبر عبارتند از:-
defaultاز منابع پیش‌فرض برای نمای خیابان استفاده می‌کند؛ جستجوها محدود به منابع خاصی نیستند. -
outdoorجستجوها را به مجموعه‌های فضای باز محدود می‌کند. مجموعه‌های فضای بسته در نتایج جستجو لحاظ نمی‌شوند. توجه داشته باشید که ممکن است تصاویر پانورامای فضای باز برای مکان مشخص شده وجود نداشته باشند. همچنین توجه داشته باشید که جستجو فقط پانوراماهایی را برمی‌گرداند که در آنها بتوان تشخیص داد که آیا آنها در فضای بسته هستند یا در فضای باز. به عنوان مثال، PhotoSphereها برگردانده نمی‌شوند زیرا مشخص نیست که آیا آنها در فضای باز هستند یا در فضای بسته.
-
این یک نمونه درخواست است.
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
تصویری موجود نیست
برای مکان‌هایی که تصاویر نمای خیابان در دسترس نیست، API نمای خیابان استاتیک یک تصویر خاکستری عمومی با متن "متاسفیم، ما اینجا تصویری نداریم" برمی‌گرداند، همانطور که در این مثال نشان داده شده است:
فقط تصاویر معتبر را نمایش دهید
برای جلوگیری از نمایش تصویر عمومی و اطمینان از اینکه صفحه وب شما فقط تصاویر معتبر Street View Static API را نمایش می‌دهد، این پیشنهادات را دنبال کنید:
- پارامتر
return_error_codeرویtrueتنظیم کنید. این باعث می‌شود API نمای خیابان استاتیک، در صورت عدم وجود تصویر برای مکان مشخص شده، به جای تصویر خاکستری عمومی، خطای 404 NOT FOUND را برگرداند. - قبل از ارسال درخواست، درخواست فراداده تصویر نمای خیابان را بدهید تا مشخص شود آیا تصویری برای مکان مشخص شده موجود است یا خیر.