مقدمه
درخواست‌های فراداده استاتیک API نمای خیابان داده‌هایی را درباره پانورامای نمای خیابان ارائه می‌کنند. با استفاده از ابرداده، می‌توانید دریابید که آیا یک تصویر نمای خیابان در یک مکان مشخص در دسترس است یا خیر، و همچنین دسترسی برنامه‌ریزی شده به مختصات طول و عرض جغرافیایی، شناسه پانوراما، تاریخ گرفتن عکس و اطلاعات حق نسخه‌برداری تصویر را دریافت کنید. دسترسی به این ابرداده به شما امکان می دهد رفتار خطا را در برنامه خود سفارشی کنید.
درخواست‌های فراداده API Static View Street بدون هزینه در دسترس هستند. هیچ سهمیه ای در هنگام درخواست ابرداده مصرف نمی شود. سهمیه فقط زمانی مصرف می‌شود که تصویری را با استفاده از نمای خیابان استاتیک API بارگیری کنید.
هنگام درخواست فراداده تصاویر نمای خیابان، تصاویر پانوراما تا 50 متر دقیق هستند.
به فراداده تصاویر دسترسی داشته باشید
درخواست فراداده تصویر نمای خیابان یک URL HTTP به شکل زیر است:
https://maps.googleapis.com/maps/api/streetview/metadata?parameters
همانطور که در URL ها استاندارد است، تمام پارامترها با استفاده از علامت علامت (&) از هم جدا می شوند.
پارامترهای مورد نیاز برای درخواست های ابرداده
درخواست‌های فراداده همان پارامترهای URL را می‌پذیرند که درخواست‌های تصویری استاتیک 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 . توجه داشته باشید که این پارامترها روی داده‌های پانوراما یا پانورامای یافت شده تأثیری ندارند. API اجازه می دهد تا پارامترهای مشابه درخواست تصویر را در بر بگیرد تا ساخت یک درخواست فراداده مربوط به یک درخواست تصویری خاص را آسان تر کند، اما برای درخواست های ابرداده، API پارامترهای اختیاری و مقادیر آنها را نادیده می گیرد. برای کسب اطلاعات در مورد استفاده از این پارامترها، به راهنمای توسعه‌دهنده API Static View Street مراجعه کنید.
فرمت پاسخ
پاسخ‌های فراداده فقط در قالب JSON برگردانده می‌شوند.
نمونه ها
مثال 1: پانوراما پیدا شد
URL های زیر با موفقیت فراداده و تصویر همان پانوراما را درخواست می کنند.
درخواست و پاسخ فراداده
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
مثال 2: پانوراما یافت نشد
نشانی‌های اینترنتی زیر متادیتا و تصویر پانورامایی را درخواست می‌کنند که در مکان مشخص شده یا نزدیک آن یافت نمی‌شود.
درخواست و پاسخ فراداده
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 deleted Panorama IDs] (#refresh-pano) مراجعه کنید. |
"NOT_FOUND" | نشان می دهد که رشته آدرس ارائه شده در پارامتر location یافت نشد. این پیام ممکن است در صورتی رخ دهد که یک آدرس ناموجود داده شود. |
"OVER_QUERY_LIMIT" | نشان می دهد که شما از سهمیه روزانه یا سهمیه هر ثانیه خود برای این API فراتر رفته اید. |
"REQUEST_DENIED" | نشان می دهد که درخواست شما رد شده است. این پیام ممکن است در صورتی رخ دهد که درخواست خود را تأیید نکرده باشید، یا اگر نمای خیابان استاتیک API در پروژه کنسول Google Cloud حاوی کلید API شما فعال نشده باشد. |
"INVALID_REQUEST" | به طور کلی نشان می دهد که پارامترهای پرس و جو (آدرس، مختصات طول و عرض جغرافیایی، یا مؤلفه ها) وجود ندارد. |
"UNKNOWN_ERROR" | نشان می دهد که درخواست به دلیل خطای سرور قابل پردازش نیست. این موضوع اغلب موقتی است. اگر دوباره تلاش کنید ممکن است درخواست با موفقیت انجام شود. |
اطلاعات بیشتر
برای اطلاعات بیشتر در مورد استفاده از Street View Static API یا سایر محصولات Google Maps API، حتماً صفحه پشتیبانی Maps API را بررسی کنید.