مقدمه
درخواست‌های فراداده Street View Static API داده‌هایی درباره تمام‌نماهای «نمای خیابان» ارائه می‌دهد. بااستفاده از فراداده، می‌توانید متوجه شوید که آیا تصویر «نمای خیابان» در مکان مشخصی دردسترس است یا نه، و همچنین دسترسی برنامه‌ای به مختصات طول و عرض جغرافیایی، شناسه تمام‌نما، تاریخ گرفته شدن عکس، و اطلاعات حق نشر تصویر داشته باشید. دسترسی به این فراداده به شما امکان می‌دهد رفتار خطا را در برنامه‌تان سفارشی‌سازی کنید.
درخواست‌های فراداده Street View Static API بدون هزینه دردسترس است. وقتی فراداده درخواست می‌کنید، هیچ سهمیه‌ای مصرف نمی‌شود. سهمیه فقط زمانی مصرف می‌شود که تصویری را بااستفاده از Street View Static API بار کنید.
هنگام درخواست فراداده تصاویر «نمای خیابان»، تصاویر تمام‌نما تا ۵۰ متر دقیق است.
دسترسی به فراداده تصاویر
درخواست فراداده تصویر «نمای خیابان» یک نشانی وب HTTP به‌شکل زیر است:
https://maps.googleapis.com/maps/api/streetview/metadata?parameters
همان‌طور که در نشانی‌های وب استاندارد است، همه پارامترها بااستفاده از نویسه اَمپرسند (&) از هم جدا می‌شوند.
پارامترهای الزامی برای درخواست‌های فراداده
درخواست‌های فراداده همان پارامترهای نشانی وب درخواست‌های تصاویر Street View Static API را می‌پذیرند، هرچند فقط پارامترهای زیر الزامی هستند:
یکی از موارد زیر را انجام دهید:
location— می‌تواند رشته نوشتاری (مثلChagrin Falls, OH) یا جفت مختصات عرض جغرافیایی و طول جغرافیایی جداشده با کاما (40.457375,-80.009353) باشد.
یا:
pano— شناسه تمام‌نمای خاص. شناسه سراسرنماها ممکن است درطول زمان تغییر کند، بنابراین این شناسه را ذخیره نکنید. به‌جای آن، نشانی مکان یا مختصات طول و عرض جغرافیایی را ذخیره کنید تا بتوانید شناسه تمام‌نما را بازآورید. برای جزئیات، به بازآوری شناسه‌های تمام‌نمای حذف‌شده مراجعه کنید.
و همچنین:
keyوsignature— کلید میانای API برای اصالت‌سنجی درخواست لازم است. امضای دیجیتال نیز در برخی موارد الزامی است و همیشه توصیه می‌شود. برای اطلاعات بیشتر، به دریافت کلید و امضا مراجعه کنید.
درخواست فراداده شما، فقط با پارامترهای الزامی، به‌این‌صورت است:
https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>
یا به این صورت:
https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>
بازآوری شناسه‌های تمام‌نمای حذف‌شده
اگر تلاش کنید شناسه تمام‌نما را بازیابی کنید و ZERO_RESULTS یا
هیچ مقداری دریافت نکنید، شناسه تمام‌نما حذف شده است و باید بازآوری شود.
نشانی مکان یا مختصات طول و عرض جغرافیایی را که برای دریافت شناسه تمام‌نما استفاده کردید ذخیره کنید تا بتوانید درصورت نیاز بازآوری کنید.
وقتی متوجه شدید که شناسه تمام‌نما تغییر کرده است، از نشانی مکان اصلی یا مختصات طول و عرض جغرافیایی استفاده کنید تا دوباره نزدیک‌ترین تمام‌نماها به آن مکان را جستجو کنید و شناسه تمام‌نمای جدیدی دریافت کنید.
پارامترهای اختیاری برای درخواست‌های فراداده
می‌توانید پارامترهای زیر را در درخواست فراداده خود بگنجانید: size،
heading، fov، و pitch. توجه داشته باشید که این پارامترها بر داده‌های مربوط به تمام‌نما یا اینکه کدام تمام‌نما پیدا شود تأثیری ندارند.
این میانای برنامه‌سازی کاربردی امکان گنجاندن همان پارامترهای
درخواست تصاویر
را فراهم می‌کند تا ساختن درخواست فراداده مربوط به درخواست تصاویر خاص آسان‌تر شود،
اما برای درخواست‌های فراداده، میانای برنامه‌سازی کاربردی پارامترهای اختیاری و
مقادیر آن‌ها را نادیده می‌گیرد. برای کسب اطلاعات درباره استفاده از این پارامترها، به
راهنمای توسعه‌دهنده Street View Static API مراجعه کنید.
قالب پاسخ
پاسخ‌های فراداده فقط در قالب JSON برگردانده می‌شوند.
مثال‌ها
مثال ۱: تمام‌نما پیدا شد
نشانی‌های وب زیر با موفقیت فراداده و تصویر همان تمام‌نما را درخواست می‌کنند.
درخواست و پاسخ فراداده
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"copyright" : "© 2017 Google",
"date" : "2016-05",
"location" : {
"lat" : 48.85783227207914,
"lng" : 2.295226175151347
},
"pano_id" : "tu510ie_z4ptBZYo2BGEJg",
"status" : "OK"
}درخواست و پاسخ تصاویر، جایی که تصویر مفقودشده انتظار می‌رود.
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
مثال ۲: تمام‌نما پیدا نشد
نشانی‌های وب زیر فراداده و تصویر تمام‌نمایی را درخواست می‌کنند که در مکان مشخص‌شده یا نزدیک آن پیدا نشد.
درخواست و پاسخ فراداده
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"status" : "ZERO_RESULTS"
}درخواست و پاسخ تصاویر
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
کدهای وضعیت
فیلد status در شیء پاسخ فراداده حاوی وضعیت درخواست است و ممکن است حاوی اطلاعات اشکال‌زدایی باشد تا به شما کمک کند دلیل کار نکردن درخواست «نمای خیابان» را عیب‌یابی کنید. فیلد status ممکن است حاوی
مقادیر زیر باشد:
| وضعیت | شرح |
|---|---|
"OK" |
نشان می‌دهد که خطایی رخ نداده است؛ تمام‌نما پیدا شده و فراداده برگردانده شده است. |
"ZERO_RESULTS" |
نشان می‌دهد که هیچ تمام‌نمایی در نزدیکی مکان ارائه‌شده پیدا نشد. این پاسخ ممکن است زمانی رخ دهد که شناسه تمام‌نمای نامعتبر یا غیرموجود ارائه دهید. [بازآوری شناسه‌های تمام‌نمای حذف‌شده](#refresh-pano) را ببینید. |
"NOT_FOUND" |
نشان می‌دهد که رشته نشانی ارائه‌شده در پارامتر location
پیدا نشد. این پیام ممکن است زمانی نشان داده شود که نشانی‌ای که وجود ندارد
ارائه شده باشد. |
"OVER_QUERY_LIMIT" |
نشان می‌دهد که از سهمیه روزانه یا سهمیه در ثانیه خود برای این API فراتر رفته‌اید. |
"REQUEST_DENIED" |
نشان می‌دهد که درخواست شما رد شده است. این پیام ممکن است درصورتی نمایش داده شود که درخواستتان را مجاز نکرده باشید یا Street View Static API در پروژه کنسول Google Cloud حاوی کلید میانای برنامه‌سازی کاربردی شما فعال نشده باشد. |
"INVALID_REQUEST" |
عموماً نشان می‌دهد که پارامترهای پُرسمان (نشانی، مختصات طول و عرض جغرافیایی، یا مؤلفه‌ها) وجود ندارد. |
"UNKNOWN_ERROR" |
نشان می‌دهد که درخواست به‌دلیل خطای سرور پردازش نشده است. این مشکل اغلب موقتی است. اگر دوباره امتحان کنید، ممکن است درخواست موفقیت‌آمیز باشد. |
اطلاعات بیشتر
برای اطلاعات بیشتر درباره استفاده از Street View Static API، یا دیگر محصولات Google Maps API، حتماً به صفحه پشتیبانی Maps API مراجعه کنید.