‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

کاشی «نمای خیابان»

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

نمونه کاشی‌های «نمای خیابان»

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

کاشی‌های «نمای خیابان Google Maps»
فراداده «نمای خیابان»
ریزعکس‌های «نمای خیابان»

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

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

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

کد جلسه دریافت کنید. حتماً مقدار mapType را روی streetview تنظیم کنید.
از کد جلسه برای دریافت شناسه تمام‌نما (panoId) یک یا چند مکان جغرافیایی استفاده کنید.
از شناسه‌های تمام‌نما در پاسخ جستجوی panoId برای دریافت موارد زیر استفاده کنید:
1. فراداده «نمای خیابان». همچنین می‌توانید با ارسال مجموعه‌ای از مختصات و شعاع، فراداده «نمای خیابان» را دریافت کنید.
2. ریزعکس‌های «نمای خیابان».
3. کاشی «نمای خیابان».

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

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

روش	شرح
`https://tile.googleapis.com/v1/streetview/tiles`	کاشی‌های «نمای خیابان» را به‌صورت جداگانه برمی‌گرداند. می‌توانید «کاشی‌های نمای خیابان» را در شش سطح بزرگ‌نمایی بازیابی کنید: از ۵۱۲ پیکسل تا ۱۳٬۳۱۲ پیکسل.
`https://tile.googleapis.com/v1/streetview/panoIds`	به شما امکان می‌دهد تا ۱۰۰ مکان را به‌صورت انبوه جستجو کنید. شناسه‌های تمام‌نما را برای همه مکان‌های دارای تصویر برمی‌گرداند.
`https://tile.googleapis.com/v1/streetview/thumbnail`	تصویر JPEG ریزعکسی از صحنه «نمای خیابان» برمی‌گرداند. به شما امکان می‌دهد جهت، زاویه، ابعاد، و میدان دید را ارائه دهید. حداقل ابعاد ۱۶×۱۶ پیکسل است. حداکثر ابعاد ۲۵۰×۶۰۰ پیکسل است.
`https://tile.googleapis.com/v1/streetview/metadata`	اطلاعات دقیقی درباره تمام‌نمای مشخص‌شده ارائه می‌دهد. جزئیات شامل نشانی مربوطه و پیوندهای تمام‌نماهای مجاور است.

Street View panoIds search

می‌توانید شناسه تمام‌نمای یک یا چند مکان جغرافیایی را با ارسال مختصات آن‌ها (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

‫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: جهت قطب‌نما، اندازه‌گیری‌شده با درجه، ساعت‌گرد از شمال. جهت‌ها در محدوده [۰،۳۶۰] برگردانده می‌شوند که ۰ نشان‌دهنده شمال واقعی است.
tilt: شیب تمام‌نما، که با واحد درجه از قطب جنوب تمام‌نما تا افق اندازه‌گیری می‌شود. مقادیر برگردانده‌شده در محدوده [0, 180] هستند. مقدار ۹۰ درجه نشان می‌دهد که افق ازقبل در خط استوای سراسرنما تراز شده است.
roll: چرخش ساعت‌گرد حول خط دید که برای تراز کردن افق روی تمام‌نما اعمال شده است. مقادیر برگردانده‌شده در محدوده [۰، ۳۶۰] هستند.
imageryType: نوع تصویر را نشان می‌دهد. مقادیر معتبر indoor و outdoor است.
date: تاریخی که تصویر گرفته شده است. همه تصاویر داده‌های تاریخ ندارند. اما وقتی دردسترس باشد، این فیلد ترکیبی از سال (YYYY) و ماه (MM) را دربرمی‌گیرد. برای مثال: 2023-05، یا 2024.
copyright: نوشتار حق نشر که باید به‌عنوان ارجاع همراه با تصویر «نمای خیابان» نمایش دهید.
reportProblemLink: اَبَرپیوندی برای کاربران شما تا از آن برای گزارش کردن مشکلات مربوط به این کاشی نمای خیابان استفاده کنند. باید این اَبَرپیوند را در گوشه پایین سمت راست تصویر نمایش دهید و باید شامل نوشتار پیوندی باشد که چیزی شبیه به «گزارش مشکل در این تصویر» را بیان کند.
addressComponent: یک زمین‌کدیاب ساختاریافته که حاوی جزئیاتی درباره نشانی تمام‌نما است. برای اطلاعات بیشتر، درخواست‌ها و پاسخ‌های زمین‌کدیابی را در اسناد Geocoding 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"

نمونه کد زیر را درنظر بگیرید که ریزعکسی از تصاویر «نمای خیابان» گرفته‌شده در ویسلر، کانادا را بارگیری می‌کند.

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: کلید میانای برنامه‌سازی کاربردی شما.

پارامترهای اختیاری

height: ارتفاع ریزعکس را به پیکسل مشخص می‌کند، از ۱۶ پیکسل تا ۲۵۰ پیکسل. اگر ارتفاع را مشخص نکنید، ارتفاع به‌طور پیش‌فرض روی حداکثر مقدار مجاز ۲۵۰ پیکسل تنظیم می‌شود. اگر مقداری را مشخص کنید که خارج از محدوده باشد، تصویر کوچک به نزدیک‌ترین مقدار معتبر می‌چسبد.
width: عرض ریزعکس را برحسب پیکسل مشخص می‌کند، از ۱۶ پیکسل تا ۶۰۰ پیکسل. اگر عرض را مشخص نکنید، عرض به‌طور پیش‌فرض روی حداکثر مقدار مجاز ۶۰۰ پیکسل تنظیم می‌شود. اگر مقداری را مشخص کنید که خارج از محدوده باشد، تصویر کوچک به نزدیک‌ترین مقدار معتبر می‌پرد.
pitch: زاویه دوربین را در امتداد محور عمودی مشخص می‌کند. مقادیر معتبر در محدوده -90 تا 90 (شامل این دو عدد) است. مقدار پیش‌فرض ۰ است.
yaw: جهت دوربین را در امتداد محور افقی مشخص می‌کند. مقادیر معتبر در محدوده -360 تا 360 (شامل این دو عدد) است. مقدار پیش‌فرض ۰ است.
fov: میدان دید افقی را برحسب درجه با حداکثر مقدار ۱۲۰ مشخص می‌کند. هنگام کار با نمای دید با اندازه ثابت، مانند تصویر «نمای خیابان» با اندازه مشخص، میدان دید نشان‌دهنده بزرگ‌نمایی است؛ جایی که مقادیر کوچک‌تر سطح بالاتری از بزرگ‌نمایی را مشخص می‌کنند. مقدار پیش‌فرض ۹۰ است.

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

وقتی 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	۳۶۰ درجه
1	‎۱۸۰°
2	‎۹۰°
3	‫۴۵ درجه
4	‫۲۲٫۵ درجه
5	‫۱۱٫۲۵ درجه

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

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

نتیجه درخواست موفقیت‌آمیز «کاشی»

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

سطح بزرگ‌نمایی صفر

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

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

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