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

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

• کاشی‌های نمای خیابان گوگل مپس
• فراداده نمای خیابان
• تصاویر کوچک نمای خیابان

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

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

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

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

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

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

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

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

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

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

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

جستجوی 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 باید حداقل شامل یک مجموعه از مقادیر مختصات باشد، اما می‌توانید تعداد بیشتری - تا حداکثر ۱۰۰ عدد - را نیز در آن قرار دهید.

radius

مقدار radius (که بر حسب متر اندازه‌گیری می‌شود) شعاع دایره اطراف مکان داده شده را که در آن می‌توان پانوراماها را جستجو کرد، تعریف می‌کند. مقدار پیش‌فرض ۵۰ متر است.

پاسخ PanoId

API مربوط به Map Tiles سعی می‌کند تا نزدیک‌ترین پانوراما به هر مکان را پیدا کند و سپس شناسه‌های پانورامای آنها را برمی‌گرداند. یک درخواست موفقیت‌آمیز panoIds یک شیء JSON را برمی‌گرداند که حاوی یک آرایه panoIds است. این آرایه شامل لیستی از شناسه‌های پانوراما، به ترتیبی که شما درخواست کرده‌اید، می‌باشد. اگر API مربوط به Map Tiles نتواند هیچ پانورامایی برای مکان‌های درخواستی شما پیدا کند، یک رشته خالی در آن مکان در آرایه برگردانده می‌شود. برای مثال، به کد JSON زیر مراجعه کنید.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

شما می‌توانید از panoIds برای موارد زیر استفاده کنید:

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

فراداده نمای خیابان

درخواست‌های فراداده نمای خیابان، اطلاعات مربوط به تصاویر پانوراما را بازیابی می‌کنند. یک درخواست فراداده نمای خیابان، یک درخواست HTTPS GET است. می‌توانید اطلاعات مربوط به تصاویر پانوراما را به یکی از دو روش زیر بازیابی کنید:

• اگر pano_id را ارسال کنید، API مربوط به Map Tiles، متادیتای آن پانوراما را برمی‌گرداند.

• اما اگر lat و lng را ارسال کنید، API مربوط به Map Tiles، فراداده‌های مربوط به نزدیکترین پانوراما را در شعاع جستجوی داده شده برمی‌گرداند.

مجموعه‌ای از مختصات و شعاع را ارسال کنید

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

یک ژئوکد ساختاریافته که شامل جزئیاتی در مورد آدرس پانوراما است. برای اطلاعات بیشتر، به درخواست‌ها و پاسخ‌های ژئوکدینگ در مستندات API ژئوکدینگ مراجعه کنید.

links

فهرستی از شناسه‌های پانوراما که به این یکی پیوند دارند. همچنین شامل عنوانی است که پیوند در آن یافت می‌شود. برای مثال، اگر عنوان ۱۸۰ درجه باشد، پانورامای پیوند شده در جنوب پانورامای فعلی قرار دارد. توجه داشته باشید که به دلیل ماهیت گذرای شناسه‌های پانوراما، نباید بیش از یک جلسه کاربری به این شناسه‌ها تکیه کنید.

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

شما می‌توانید تصاویر نمای خیابان را در قالب 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"

به مثال کد زیر توجه کنید که یک تصویر کوچک از تصاویر Street View گرفته شده در ویستلر، کانادا را دانلود می‌کند.

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

ارتفاع تصویر بندانگشتی را بر حسب پیکسل مشخص می‌کند، که از ۱۶ پیکسل تا ۲۵۰ پیکسل متغیر است. اگر ارتفاعی مشخص نکنید، ارتفاع به طور پیش‌فرض روی حداکثر مقدار مجاز ۲۵۰ پیکسل تنظیم می‌شود. اگر مقداری خارج از محدوده مشخص کنید، تصویر بندانگشتی به نزدیکترین مقدار معتبر تغییر می‌کند .

width

عرض تصویر بندانگشتی را بر حسب پیکسل مشخص می‌کند، که از ۱۶ پیکسل تا ۶۰۰ پیکسل متغیر است. اگر عرضی مشخص نکنید، عرض به طور پیش‌فرض روی حداکثر مقدار مجاز ۶۰۰ پیکسل تنظیم می‌شود. اگر مقداری خارج از محدوده مشخص کنید، تصویر بندانگشتی به نزدیکترین مقدار معتبر تغییر می‌کند .

pitch

زاویه دوربین را در امتداد محور عمودی مشخص می‌کند. مقادیر معتبر در محدوده -90 تا 90 (شامل) هستند. مقدار پیش‌فرض ۰ است.

yaw

جهت دوربین را در امتداد محور افقی مشخص می‌کند. مقادیر معتبر در محدوده -360 تا 360 (شامل) هستند. مقدار پیش‌فرض s 0 است.

fov

میدان دید افقی را که بر حسب درجه بیان می‌شود، با حداکثر مقدار ۱۲۰ مشخص می‌کند. هنگام کار با یک نمای ثابت، مانند تصویر نمای خیابان با اندازه مشخص، میدان دید نشان‌دهنده بزرگنمایی است؛ جایی که مقادیر کوچکتر، سطح بالاتری از بزرگنمایی را مشخص می‌کنند. مقدار پیش‌فرض ۹۰ است.

کاشی‌های تصویر نمای خیابان

وقتی یک panoId دارید، می‌توانید درخواست کاشی تصویر نمای خیابان (Street View image tile) بدهید. درخواست‌های کاشی، درخواست‌های 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 نشان دهنده وسیع ترین میدان دید است.

پاسخ‌های کاشی‌های نمای خیابان

یک درخواست کاشی نمای خیابان موفق، تصویری با فرمت و اندازه‌ای که در پاسخ createSession خود مشخص کرده‌اید را برمی‌گرداند.

در سطح زوم صفر، کل تصویر پانوراما به صورت کاشی با ابعاد tileWidth در tileHeight تغییر اندازه می‌دهد. از آنجا که تصاویر پانوراما در بعد x بزرگتر هستند، کاشی در بعد y فضای خالی خواهد داشت:

در زوم سطح پنج، از پانورامای تمام‌قد استفاده می‌شود و به قطعات کوچک تقسیم می‌شود.

اطلاعات حق نشر

شما باید اطلاعات حق نشر را با هر پانورامای نمای خیابان نمایش دهید. رشته‌ای که نمایش داده می‌شود می‌تواند بین پانوراماها متفاوت باشد. برای دریافت اطلاعات حق نشر، باید فراداده نمای خیابان را درخواست کنید و سپس می‌توانید به فیلد copyright پاسخ مراجعه کنید. برای اطلاعات بیشتر، به بخش «نسبت‌های داده» مراجعه کنید.