مقدمه
درخواست‌های فراداده‌ی API نمای خیابان استاتیک، داده‌هایی در مورد پانوراماهای نمای خیابان ارائه می‌دهند. با استفاده از فراداده، می‌توانید بفهمید که آیا تصویر نمای خیابان در یک مکان مشخص موجود است یا خیر، و همچنین به مختصات عرض و طول جغرافیایی، شناسه‌ی پانوراما، تاریخ گرفته شدن عکس و اطلاعات حق نشر تصویر، از طریق برنامه‌نویسی دسترسی پیدا کنید. دسترسی به این فراداده به شما امکان می‌دهد رفتار خطا را در برنامه‌ی خود سفارشی کنید.
درخواست‌های فراداده‌ی API نمای خیابان استاتیک بدون هزینه در دسترس هستند. هنگام درخواست فراداده، هیچ سهمیه‌ای مصرف نمی‌شود. سهمیه فقط هنگام بارگذاری تصویری با استفاده از API نمای خیابان استاتیک مصرف می‌شود .
هنگام درخواست‌های فراداده تصاویر نمای خیابان، دقت تصاویر پانوراما تا ۵۰ متر است.
دسترسی به فراداده تصاویر
درخواست فراداده تصویر نمای خیابان، یک 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 پارامترهای اختیاری و مقادیر آنها را نادیده می‌گیرد. برای اطلاعات در مورد استفاده از این پارامترها، به راهنمای توسعه‌دهنده Street View Static API مراجعه کنید.
قالب پاسخ
پاسخ‌های متادیتا فقط در قالب JSON برگردانده می‌شوند.
مثال‌ها
مثال ۱: پانوراما پیدا شد
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
مثال ۲: پانوراما پیدا نشد
آدرس‌های اینترنتی زیر، فراداده و تصویر یک پانوراما را درخواست می‌کنند که در محل مشخص‌شده یا نزدیک آن یافت نمی‌شود.
درخواست و پاسخ فراداده
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" | نشان می‌دهد که درخواست به دلیل خطای سرور قابل پردازش نیست. این مشکل اغلب موقتی است. اگر دوباره امتحان کنید، ممکن است درخواست با موفقیت انجام شود. |
اطلاعات بیشتر
برای اطلاعات بیشتر در مورد استفاده از API استاتیک نمای خیابان یا سایر محصولات API نقشه‌های گوگل، حتماً صفحه پشتیبانی API نقشه‌ها را بررسی کنید.