کاشیهای نمای خیابان شبیه به کاشیهای دوبعدی هستند با این تفاوت که حاوی تصاویر پانوراما هستند که در سطح خیابان گرفته شدهاند. با نمای خیابان، میتوانید نقاط دیدنی جهان را کاوش کنید، شگفتیهای طبیعی را ببینید و به مکانهایی مانند موزهها، میدانها، رستورانها یا کسبوکارهای کوچک قدم بگذارید. این نقطه پایانی API به شما امکان دسترسی به موارد زیر را می دهد:
- کاشیهای نمای خیابان Google Maps
- فراداده نمای خیابان
- تصاویر کوچک نمای خیابان
میتوانید کاشیهای تصویر گرفتهشده از سطح خیابان را به هم بپیچید تا جلوهای پانوراما در زندگی واقعی ایجاد کنید. و میتوانید تا 100 شناسه پانوراما را برای مجموعهای از مکانها (مانند یک مسیر) جستجو کنید و فرادادههای عمیقتری درباره موقعیت دوربین دریافت کنید.
بیننده لازم است تا کاشیهای نمای خیابان را به هم بپیچد. برای مثال، نمایشگر پانورامای سفارشی نمای خیابان .
هنگامی که یک کلید API دارید، می توانید با انجام مراحل زیر به تصاویر نمای خیابان دسترسی داشته باشید.
یک نشانه جلسه دریافت کنید. حتماً مقدار
mapType
را رویstreetview
تنظیم کنید.از نشانه جلسه برای دریافت شناسه پانوراما (panoId) یک یا چند مکان جغرافیایی استفاده کنید.
از شناسه های پانوراما از پاسخ جستجوی panoId برای دریافت موارد زیر استفاده کنید:
فراداده نمای خیابان همچنین میتوانید با عبور مجموعهای از مختصات و شعاع، متادیتای نمای خیابان را دریافت کنید.
روش های نمای خیابان
با فراخوانی یکی از چهار روش زیر میتوانید به تصاویر و ابردادههای نمای خیابان دسترسی داشته باشید.
روش | توضیحات |
---|---|
https://tile.googleapis.com/v1/streetview/tiles | تک تک کاشیهای نمای خیابان را برمیگرداند. میتوانید کاشیهای نمای خیابان را در شش سطح بزرگنمایی بازیابی کنید: از ۵۱۲ پیکسل تا ۱۳۳۱۲ پیکسل. |
https://tile.googleapis.com/v1/streetview/panoIds | به شما امکان می دهد تا 100 مکان را به صورت انبوه جستجو کنید. شناسههای پانوراما را برای همه مکانهای دارای تصویر برمیگرداند. |
https://tile.googleapis.com/v1/streetview/thumbnail | یک تصویر کوچک JPEG از یک صحنه نمای خیابان را برمیگرداند. به شما امکان می دهد عنوان، زمین، ابعاد و میدان دید را ارائه دهید. حداقل ابعاد 16x16 پیکسل است. حداکثر ابعاد 250x600 پیکسل است. |
https://tile.googleapis.com/v1/streetview/metadata | اطلاعات دقیقی در مورد پانورامای مشخص شده ارائه می دهد. جزئیات شامل آدرس مربوطه، و پیوندهایی به پانورامای مجاور است. |
جستجوی panoIds نمای خیابان
می توانید شناسه پانورامای یک یا چند مکان جغرافیایی را با ارسال مختصات آنها ( lat
، lng
) به روش panoIds
پیدا کنید. بدنه درخواست یک شی JSON است که شامل یک آرایه locations
و به صورت اختیاری، یک radius
، همانطور که در مثال کد JSON زیر نشان داده شده است.
curl -X POST -d '{ "locations": [ {"lat": -33.883837, "lng": 151.209307}, {"lat": -33.883700, "lng": 151.210307}, {"lat": 0, "lng": 0} ], "radius": 50 }' \ -H 'Content-Type: application/json' \ "https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY"
-
locations
- آرایه
locations
باید حداقل شامل یک مجموعه از مقادیر مختصات باشد، اما شما می توانید تعداد بیشتری را تا حداکثر 100 اضافه کنید. -
radius
- مقدار
radius
(اندازهگیری شده بر حسب متر) شعاع دایره را در اطراف مکان داده شده مشخص میکند که در آن پانوراما جستجو میشود. مقدار پیش فرض 50 متر است.
پاسخ PanoId
Map Tiles API سعی می کند نزدیکترین پانوراما به هر مکان را پیدا کند و سپس شناسه پانورامای آنها را برمی گرداند. یک درخواست موفق panoIds
یک شی JSON را برمی گرداند که حاوی آرایه panoIds
است. آرایه حاوی لیستی از شناسه های پانوراما است، به ترتیبی که آنها را درخواست کردید. اگر Map Tiles API نتواند هیچ پانورامایی برای مکانهایی که درخواست کردهاید پیدا کند، یک رشته خالی در آن مکان در آرایه برگردانده میشود. برای مثال، کد JSON زیر را ببینید.
{
"panoIds": [
"ACfH-n2HcBvRry_3oc9grw",
"f5DJZatBAAAXHlooS2wKbw",
""
]
}
می توانید از panoIds
برای موارد زیر استفاده کنید:
- فراداده نمای خیابان را درخواست کنید
- تصاویر کوچک نمای خیابان را درخواست کنید
- کاشی نمای خیابان را درخواست کنید
فراداده نمای خیابان
درخواستهای فراداده نمای خیابان اطلاعات مربوط به پانوراما را بازیابی میکند. درخواست فراداده نمای خیابان یک درخواست HTTPS GET است. می توانید اطلاعات مربوط به پانوراما را به یکی از دو روش بازیابی کنید:
اگر یک
pano_id
پاس کنید، Map Tiles API ابرداده را برای آن پانوراما برمیگرداند.اما اگر از
lat
وlng
عبور کنید، Map Tiles API ابرداده را برای نزدیکترین پانوراما در شعاع جستجوی داده شده برمی گرداند.
مجموعه ای از مختصات و یک شعاع را رد کنید
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY &lat=lat &lng=lng &radius=meters"
از آنجایی که شناسههای پانوراما گذرا هستند، توصیه میکنیم مجموعهای از مختصات و یک مقدار radius
را در درخواست اولیه ابرداده نمای خیابان ارسال کنید. برای مثال، قطعه کد زیر را ببینید.
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &lat=47.62066 &lng=-122.34923 &radius=50"
panoId یک تصویر نمای خیابان را پاس کنید
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId"
پاسخ فراداده
کد JSON زیر نمونه ای از پاسخ متادیتای معمولی است.
{
"panoId": "rZ9KeTyhA11i0VppYNzsSg",
"lat": 37.420864219339165,
"lng": -122.08446528377291,
"imageHeight": 6656,
"imageWidth": 13312,
"tileHeight": 512,
"tileWidth": 512,
"heading": 94.35,
"tilt": 88.39652,
"roll": 1.7181772,
"imageryType": "outdoor",
"date": "2023-01",
"copyright": "© 2023 Google",
"reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
"addressComponents": [
{
"longName": "United States",
"shortName": "United States",
"types": [
"country"
]
},
{
"longName": "Mountain View, California",
"shortName": "Mountain View, California",
"types": [
"locality"
]
},
{
"longName": "Charleston Rd",
"shortName": "Charleston Rd",
"types": [
"route"
]
},
{
"longName": "1635",
"shortName": "1635",
"types": [
"street_number"
]
}
],
"links": [
{
"panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
"heading": 274.47998046875,
"text": "Charleston Rd"
},
{
"panoId": "1cODYwFRw1aZ45IignDIMw",
"heading": 94.47999572753906,
"text": "Charleston Rd"
}
]
}
لیست زیر شامل تعاریف فیلدهای بدنه پاسخ است.
-
panoId
- شناسه منحصر به فرد این پانوراما. شما نباید به اعتبار شناسه های پانوراما بیش از یک جلسه کاربر تکیه کنید.
-
lat
،lng
- مختصات (طول و عرض جغرافیایی) پانوراما. این مقادیر میتوانند با مختصاتی که در درخواست ارسال کردهاید متفاوت باشند، زیرا مکان به نزدیکترین پانوراما میخورد .
-
imageHeight
،imageWidth
- ابعاد تصویر پانورامای دوخته شده.
-
tileHeight
،tileWidth
- ابعاد یک کاشی پانوراما.
-
heading
- جهت قطب نما، بر حسب درجه، در جهت عقربه های ساعت از شمال اندازه گیری می شود. عناوین در محدوده [0,360] بازگردانده می شوند که 0 نشان دهنده شمال است.
-
tilt
- شیب پانوراما، بر حسب درجه از قطب جنوب پانوراما تا افق اندازه گیری می شود. مقادیر برگشتی در محدوده [0، 180] هستند. مقدار 90 درجه نشان می دهد که افق از قبل در خط استوای پانوراما قرار دارد.
-
roll
- چرخش در جهت عقربه های ساعت حول خط دید که در پانوراما اعمال شد تا افق را هموار کند. مقادیر برگشتی در محدوده [0، 360] هستند.
-
imageryType
- نوع تصویر را نشان می دهد. مقادیر معتبر
indoor
وoutdoor
هستند. -
date
- تاریخی که تصویر گرفته شده است. همه تصاویر داده تاریخ ندارند. اما وقتی در دسترس باشد، این فیلد ترکیبی از سال (YYYY) و ماه (MM) را در بر می گیرد. به عنوان مثال: 2023-05، یا 2024.
-
copyright
- متن حق نسخه برداری که باید به عنوان منبع به همراه تصویر نمای خیابان نمایش دهید.
-
reportProblemLink
- پیوندی برای کاربران شما برای گزارش مشکلات مربوط به این کاشی نمای خیابان. شما باید این هایپرلینک را در گوشه سمت راست پایین تصویر نمایش دهید، و باید متن پیوندی را داشته باشد که چیزی مانند "گزارش مشکل با این تصویر" را نشان دهد.
-
addressComponent
- یک ژئوکد ساختاریافته که حاوی جزئیات مربوط به آدرس پانوراما است. برای اطلاعات بیشتر، به درخواستها و پاسخهای Geocoding در مستندات Geocoding API مراجعه کنید.
-
links
- فهرستی از شناسه های پانوراما که به این شناسه پیوند دارند. همچنین حاوی عنوانی است که پیوند در آن یافت می شود. برای مثال، اگر عنوان 180 درجه باشد، پس پانورامای پیوند داده شده در جنوب پانورامای فعلی است. توجه داشته باشید که به دلیل ماهیت گذرا شناسه های پانوراما، نباید بیش از یک جلسه کاربر به این شناسه ها اعتماد کنید.
تصاویر کوچک نمای خیابان
میتوانید تصاویر نمای خیابان را در قالب thumbnail
درخواست کنید. ریز عکسها تصاویر غیر کاشی کاری شده با اندازه، عنوان، زمین و میدان دید تعریف شده توسط کاربر هستند. تصاویر بند انگشتی وضوح کمتری نسبت به کاشی ها دارند و از نظر اندازه فایل کوچکتر هستند. همانطور که در نمونه اولیه کد زیر نشان داده شده است، با ارسال یک درخواست GET به نقطه پایانی thumbnail
، درخواست تصویر کوچک میکنید.
curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId &height=FROM_16_TO_250 &width=FROM_16_TO_600 &pitch=FROM-90_TO_90 &yaw=FROM-360_TO_360 &fov=FROM_30_TO_120"
مثال کد زیر را در نظر بگیرید که تصویر کوچکی از تصاویر نمای خیابان گرفته شده در ویستلر، کانادا را دانلود می کند.
curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=Zzl28rqGJgaL2IdkUleP8A &height=200 &width=200 &pitch=0 &yaw=250 &fov=80" --output /tmp/example_thumbnail.png
پارامترهای مورد نیاز
-
panoId
- شناسه منحصر به فرد تصویر کوچکی که می خواهید. میتوانید مقادیر شناسه پانوراما را از نقطه پایانی
panoIds
یا از نقطه پایانیmetadata
دریافت کنید - که هر دو مختصات جغرافیایی را میپذیرند وpanoId
مناسب را برمیگردانند. -
session
- یک نشانه جلسه معتبر
-
key
- کلید API شما
پارامترهای اختیاری
-
height
- ارتفاع تصویر کوچک را بر حسب پیکسل مشخص می کند که از 16 پیکسل تا 250 پیکسل متغیر است. اگر ارتفاعی را مشخص نکنید، ارتفاع به طور پیش فرض روی حداکثر مقدار مجاز 250 پیکسل است. اگر مقداری را مشخص کنید که خارج از محدوده است، تصویر کوچک به نزدیکترین مقدار معتبر میخورد .
-
width
- عرض تصویر کوچک را بر حسب پیکسل مشخص می کند که از 16 پیکسل تا 600 پیکسل متغیر است. اگر عرض را مشخص نکنید، عرض به طور پیش فرض روی حداکثر مقدار مجاز 600 پیکسل است. اگر مقداری را مشخص کنید که خارج از محدوده است، تصویر کوچک به نزدیکترین مقدار معتبر میخورد .
-
pitch
- زاویه دوربین را در امتداد محور عمودی مشخص می کند. مقادیر معتبر در محدوده
-90
تا90
(شامل) هستند. مقدار پیش فرض 0 است. -
yaw
- جهت دوربین را در امتداد محور افقی مشخص می کند. مقادیر معتبر در محدوده
-360
تا360
(شامل) هستند. مقدار پیش فرض s 0. -
fov
- میدان دید افقی را که بر حسب درجه بیان میشود، با حداکثر مقدار 120 مشخص میکند. وقتی با یک نمای با اندازه ثابت سروکار داریم، مانند یک تصویر نمای خیابان با اندازه تنظیم شده، میدان دید بزرگنمایی را نشان میدهد. که در آن مقادیر کوچکتر سطح بالاتری از بزرگنمایی را مشخص می کند. مقدار پیش فرض 90 است.
کاشیهای تصویر نمای خیابان
هنگامی که یک panoId
دارید، میتوانید یک کاشی تصویر نمای خیابان درخواست کنید. درخواستهای کاشی، درخواستهای HTTPS GET هستند. مثال زیر را در نظر بگیرید.
curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId"
در این مثال کد، z
سطح بزرگنمایی است و x
و y
مختصات کاشی نمای خیابان مورد نظر شما هستند. سطوح زوم در پانورامای نمای خیابان باید در محدوده [0،5] باشد و 0 نشان دهنده وسیع ترین میدان دید باشد.
سطح زوم | میدان دید تقریبی |
---|---|
0 | 360 درجه |
1 | 180 درجه |
2 | 90 درجه |
3 | 45 درجه |
4 | 22.5 درجه |
5 | 11.25 درجه |
پاسخهای کاشیهای نمای خیابان
یک درخواست موفقیتآمیز کاشی نمای خیابان، تصویری از قالب و اندازهای را که در پاسخ createSession
خود مشخص کردهاید، برمیگرداند.
در سطح زوم صفر، اندازه کل پانوراما به یک کاشی با ابعاد tileWidth
در tileHeight
تغییر میکند. از آنجایی که پانوراماها در بعد x بزرگتر هستند، کاشی دارای فضای خالی در بعد y خواهد بود:
در سطح پنج بزرگنمایی، پانوراما در اندازه کامل استفاده می شود و به کاشی تقسیم می شود.
اطلاعات حق چاپ
شما باید اطلاعات حق نسخهبرداری را با هر پانورامای نمای خیابان نمایش دهید. رشته نمایش داده شده می تواند بین پانوراما متفاوت باشد. برای دریافت اطلاعات حق نسخهبرداری، باید فراداده نمای خیابان را درخواست کنید و سپس میتوانید به قسمت copyright
پاسخ مراجعه کنید. برای اطلاعات بیشتر، به اسناد داده مراجعه کنید.