کاشی های نمای خیابان

مثال نمای خیابان کاشی‌های نمای خیابان شبیه به کاشی‌های دوبعدی هستند با این تفاوت که حاوی تصاویر پانوراما هستند که در سطح خیابان گرفته شده‌اند. با نمای خیابان، می‌توانید نقاط دیدنی جهان را کاوش کنید، شگفتی‌های طبیعی را ببینید و به مکان‌هایی مانند موزه‌ها، میدان‌ها، رستوران‌ها یا کسب‌وکارهای کوچک قدم بگذارید. این نقطه پایانی API به شما امکان دسترسی به موارد زیر را می دهد:

  • کاشی‌های نمای خیابان Google Maps
  • فراداده نمای خیابان
  • تصاویر کوچک نمای خیابان

می‌توانید کاشی‌های تصویر گرفته‌شده از سطح خیابان را به هم بپیچید تا جلوه‌ای پانوراما در زندگی واقعی ایجاد کنید. و می‌توانید تا 100 شناسه پانوراما را برای مجموعه‌ای از مکان‌ها (مانند یک مسیر) جستجو کنید و فراداده‌های عمیق‌تری درباره موقعیت دوربین دریافت کنید.

بیننده لازم است تا کاشی‌های نمای خیابان را به هم بپیچد. برای مثال، نمایشگر پانورامای سفارشی نمای خیابان .

هنگامی که یک کلید API دارید، می توانید با انجام مراحل زیر به تصاویر نمای خیابان دسترسی داشته باشید.

  1. یک نشانه جلسه دریافت کنید. حتماً مقدار mapType را روی streetview تنظیم کنید.

  2. از نشانه جلسه برای دریافت شناسه پانوراما (panoId) یک یا چند مکان جغرافیایی استفاده کنید.

  3. از شناسه های پانوراما از پاسخ جستجوی panoId برای دریافت موارد زیر استفاده کنید:

    1. فراداده نمای خیابان همچنین می‌توانید با عبور مجموعه‌ای از مختصات و شعاع، متادیتای نمای خیابان را دریافت کنید.

    2. تصاویر کوچک نمای خیابان

    3. کاشی های نمای خیابان

روش های نمای خیابان

با فراخوانی یکی از چهار روش زیر می‌توانید به تصاویر و ابرداده‌های نمای خیابان دسترسی داشته باشید.

روش توضیحات
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 اطلاعات دقیقی در مورد پانورامای مشخص شده ارائه می دهد. جزئیات شامل آدرس مربوطه، و پیوندهایی به پانورامای مجاور است.

می توانید شناسه پانورامای یک یا چند مکان جغرافیایی را با ارسال مختصات آنها ( 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 پیکسل است. If you specify a value that's out of range, then the thumbnail snaps to the closest valid value.
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 پاسخ مراجعه کنید. برای اطلاعات بیشتر، به اسناد داده مراجعه کنید.