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

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

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

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

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

کاشی‌های «نمای خیابان 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 ریزعکسی از صحنه «نمای خیابان» را برمی‌گرداند. به شما امکان می‌دهد جهت، زاویه، ابعاد، و میدان دید را ارائه دهید. حداقل ابعاد ۱۶x۱۶ پیکسل است. حداکثر ابعاد ۲۵۰x۶۰۰ پیکسل است.
`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: شیب تمام‌نما، که با واحد درجه از قطب جنوب تمام‌نما تا افق اندازه‌گیری می‌شود. مقادیر برگردانده‌شده در محدوده [۰، ۱۸۰] است. مقدار ۹۰ درجه نشان می‌دهد که افق ازقبل در خط استوای سراسرنما تراز شده است.
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	۳۶۰ درجه
1	‎۱۸۰°
2	‎۹۰°
3	‫۴۵ درجه
4	‫۲۲٫۵ درجه
5	‫۱۱٫۲۵ درجه

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

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

نتیجه درخواست موفق کاشی

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

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

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

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

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