درخواست تصویر نمای خیابان یک 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" تبدیل کنید. Street View Static API به عکس پانوراما نزدیکترین مکان به مکان می‌خورد. هنگامی که یک رشته متن آدرس را ارائه می کنید، API ممکن است از مکان دوربین متفاوتی برای نمایش بهتر مکان مشخص شده استفاده کند. هنگامی که مختصات طول و عرض جغرافیایی را ارائه می کنید، API شعاع 50 متری را برای نزدیکترین عکس به مکان جستجو می کند. از آنجایی که تصاویر نمای خیابان به طور دوره‌ای بازخوانی می‌شوند و ممکن است هر بار عکس‌ها از موقعیت‌های کمی متفاوت گرفته شوند، ممکن است هنگام به‌روزرسانی تصاویر،locationشما به پانورامای متفاوتی تبدیل شود.
یا:
-
panoیک شناسه پانوراما خاص است. پانوراما ممکن است با گذشت زمان شناسه تغییر کند، بنابراین این شناسه را ادامه ندهید. در عوض، آدرس مکان یا مختصات طول و عرض جغرافیایی را ذخیره کنید تا بتوانید شناسه پانوراما را بازخوانی کنید. برای جزئیات، به بازخوانی شناسه های پانورامای حذف شده مراجعه کنید.
همچنین:
-
sizeاندازه خروجی تصویر را بر حسب پیکسل مشخص می کند. اندازه به صورت{width}x{height}مشخص می‌شود - برای مثال،size=600x400تصویری را با عرض 600 پیکسل و ارتفاع 400 برمی‌گرداند. -
keyبه شما امکان می دهد استفاده از API برنامه خود را در Google Cloud Console نظارت کنید و تضمین می کند که Google می تواند در صورت لزوم درباره برنامه شما با شما تماس بگیرد. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.
شناسه های پانورامای حذف شده را بازخوانی کنید
اگر می‌خواهید یک شناسه پانوراما را بازیابی کنید و ZERO_RESULTS یا بدون مقدار دریافت کنید، شناسه پانوراما حذف شده است و باید بازخوانی شود.
آدرس مکان یا مختصات طول و عرض جغرافیایی را که برای دریافت شناسه پانوراما استفاده کرده‌اید، ذخیره کنید تا بتوانید در صورت نیاز آن را بازخوانی کنید.
وقتی متوجه شدید که شناسه پانوراما تغییر کرده است، از آدرس اصلی مکان یا مختصات طول و عرض جغرافیایی استفاده کنید تا دوباره نزدیکترین پانوراما به آن مکان را جستجو کنید و یک شناسه پانوراما جدید دریافت کنید.
پارامترهای اختیاری
-
signature( توصیه می‌شود ) یک امضای دیجیتالی است که برای تأیید اینکه هر سایتی که با استفاده از کلید API شما درخواست ایجاد می‌کند مجاز به انجام این کار است استفاده می‌شود. درخواست‌هایی که شامل امضای دیجیتال نمی‌شوند ممکن است با شکست مواجه شوند. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.توجه: برای مشتریان قبلی پلتفرم Google Maps Premium Plan، امضای دیجیتال الزامی است . اطلاعات بیشتری در مورد پارامترهای احراز هویت برای مشتریان Premium Plan دریافت کنید.
-
headingنشان دهنده عنوان قطب نما دوربین است. مقادیر پذیرفته شده از0تا360هستند (هر دو مقدار شمال،90نشان دهنده شرق و180جنوب). اگر عنوانی را مشخص نکنید، مقداری محاسبه می‌شود که دوربین را به سمتlocationمشخص شده هدایت می‌کند، از نقطه‌ای که نزدیکترین عکس گرفته شده است. -
fov( پیش‌فرض90است) میدان دید افقی تصویر را که بر حسب درجه بیان می‌شود، با حداکثر مقدار مجاز120تعیین می‌کند. هنگامی که با یک درگاه دید با اندازه ثابت سروکار دارید، مانند یک تصویر نمای خیابان با اندازه تعیین شده، میدان دید در اصل بزرگنمایی را نشان می‌دهد و اعداد کوچکتر نشان‌دهنده سطح بالاتری از زوم هستند.
(چپ: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 استاتیک نمای خیابان یک تصویر عمومی خاکستری را با متن «متأسفیم، ما هیچ تصویری در اینجا نداریم» برمی‌گرداند، همانطور که در این مثال نشان داده شده است:
فقط تصاویر معتبر را نشان دهید
برای جلوگیری از نمایش تصویر عمومی و اطمینان از اینکه صفحه وب شما فقط تصاویر معتبر API Static View Street را نمایش می دهد، این پیشنهادات را دنبال کنید:
- پارامتر
return_error_codeرا رویtrueقرار دهید. این باعث می‌شود که API استاتیک نمای خیابان به جای تصویر خاکستری عمومی، خطای 404 NOT FOUND را برگرداند، اگر تصویری برای مکان مشخص‌شده در دسترس نباشد. - پیش از ارسال درخواست، فراداده تصویر نمای خیابان را درخواست کنید تا مشخص شود آیا تصاویری برای مکان مشخص شده در دسترس است یا خیر.