با توجه به یک آدرس یا شناسه ویدیویی معتبر، روش lookupVideo URI هایی را برمی گرداند که مجموعه ای از ویدیوهای Aerial View API را شناسایی می کنند. روش lookupVideo تنها زمانی URI ها را برمی گرداند که Google قبلاً یک ویدیو برای آن مکان ایجاد کرده باشد.
برای بررسی وجود ویدیو، از روش lookupVideoMetadata استفاده کنید.
نحوه استفاده از API
با عبور از آن به آدرس پستی URL رمزگذاری شده URL یا یک videoId با این نقطه پایانی تماس بگیرید.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&address=POSTAL_ADDRESS "
سپس API یکی از سه پاسخ زیر را برمی گرداند:
اگر ویدیویی وجود داشته باشد،
lookupVideoیک حالت پردازشیACTIVEو یک URI افقی و عمودی را برای هر نوع رسانه پشتیبانی‌شده و ابرداده برمی‌گرداند.اگر ویدیو در سیستم ما است، اما هنوز به طور کامل رندر نشده است،
lookupVideoیک وضعیت پردازشPROCESSING، و یکvideoIdبرمی‌گرداند که می‌توانید پس از اتمام رندر، از آن برای دریافت ویدیو استفاده کنید.اگر ویدیو هنوز وجود نداشته باشد، API یک کد وضعیت 404 را برمی‌گرداند. در این صورت، می‌توانید با فراخوانی
renderVideoیک ویدیوی جدید تولید کنید .
نحوه استفاده از URI های ویدیوی برگشتی
روش lookupVideo را یک بار در هر آدرس یا videoID در هر نمایش فراخوانی کنید. URI های ویدئویی در پاسخ به عنوان URI های کوتاه مدت نامیده می شوند و پس از مدت کوتاهی منقضی می شوند.
گوگل اغلب ویدیوها را به روز می کند. بنابراین، برای اطمینان از اینکه جدیدترین محتوا را برای مشتریان خود نمایش می دهید، هر بار که ویدیویی را نمایش می دهید، با روش lookupVideo تماس بگیرید.
پشتیبانی از ویدیوهای در دسترس
برای پشتیبانی از دسترس‌پذیری، Google توصیه می‌کند وقتی یک ویدیوی نمای هوایی را برای مشتریان خود نمایش می‌دهید، رونوشت یا شرح ویدیو اضافه کنید. به این ترتیب، یک صفحه‌خوان می‌تواند رونوشت یا توضیحات آن را به کاربر اعلام کند.
به عنوان مثال، یک توضیح در فرم اضافه کنید:
"این یک نمای هوایی واقعی از ADDRESS است که توسط Google Maps ارائه شده است."
به‌جای آدرس، می‌توانید توضیحی درباره ویدیو به این شکل اضافه کنید:
این یک نمای هوایی فوتورئالیستی از ساختمان امپایر استیت در نیویورک است که توسط Google Maps ارائه شده است.
شناسه های ویدیویی را برای استفاده بعدی ذخیره کنید
با توجه به شرایط خاص سرویس برای Aerial View API، شناسه‌های ویدیوی Aerial View API از محدودیت‌های ذخیره‌سازی ذکر شده در بخش 3.2.3(b) (بدون ذخیره‌سازی در حافظه پنهان) شرایط خدمات پلتفرم Google Maps مستثنی هستند. بنابراین می توانید مقادیر ID ویدیو را برای استفاده بعدی ذخیره کنید.
درخواست مثال برای ارسال یک آدرس
نمونه کد زیر یک ویدیوی نمای هوایی برای هرم Transamerica، واقع در 600 Montgomery St, San Francisco, CA 94111 درخواست می کند.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&address=600%20Montgomery%20St%2C%20San%20Francisco%2C%20CA%2094111"
پاسخ نمونه
مثال‌های JSON زیر تمام پاسخ‌های ممکن به درخواست lookupVideo را نشان می‌دهند.
ویدیو پیدا شد
اگر ویدیویی که درخواست می‌کنید وجود داشته باشد، API فهرستی از URIها را برمی‌گرداند که هر کدام به فرمت یا نسخه دیگری از ویدیوی درخواستی پیوند دارند. برای آشنایی با فرمت های مختلف، نگاه کنید به MPEG-DASH چیست؟ | HLS در مقابل DASH .
{
"uris": {
"IMAGE": {
"landscapeUri": "https://www.gstatic.com/aerialview/thumbnail/-1202461100507922431.jpg?sqp=CKiU6qIGGPQD&rs=AHRQkOe1j6EA5Q3WzJgDluv8AXbNlZ8M-g",
"portraitUri": "https://www.gstatic.com/aerialview/thumbnail/2256303413312618497.jpg?sqp=CKiU6qIGGPQD&rs=AHRQkOelSBTTVgOmFrSZ71c1xjyuoSBAAA"
},
"MP4_HIGH": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=375&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=37357139&dur=40.016&lmt=1683384545351664&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRgIhAOhUzpUZGXThRz481S5YAVoy7d7V29-8GDRWLdDEtzagAiEA5laBMqKNnoPCeTHFVT56FYQ5MZp7pZTtDNp9tSJffyc=&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgVqK6hzOoDaTnWt4UmIQgXOyGCc5Pxf4tmp2t6YzwkrQCIQCCOsPpfT2g_BT32Ki_iMwwBb2IhoquVISoHbBMI5_dAw==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=375&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=11844099&dur=40.016&lmt=1683384626250758&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRgIhAPP030ASCfKrXHpu72d78SBN_3T-7jKQ5_OjAvVzvYLaAiEAhEDAo689v0DWSCkfxxD8oU2iJVifC25Q7gQplx5_25U=&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgREl7bSQ_z9Y86A_bRnX1RdQqoIbwgjV2rEkhLlNilBICIQC9amH8IwmRdbbcCUxnSttBjcy_4BwiBBbSd_PM1KgICw=="
},
"MP4_LOW": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=134&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=3152145&dur=39.999&lmt=1683384843730359&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRAIgVDf8P_aMLthAC6ASciANODNo7p7IqofngIgCUnfUofYCICV7JexvuPTnaqOfShKIL33uhtzIfnfOj2LgfpY0zKdx&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIhAM2jKSXegkPbIFD4L7H6FeBz5ytYtMkXNfowGlAB9aL2AiA3DQJIeoTfs3EOIPMfDBCGm7v_vWTruRBjXLN4lRIa-Q==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=134&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=1002125&dur=39.999&lmt=1683384248881200&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRAIgYRyzRjtsGYFcodlU4-SvJ9GRgx97MF1nFlhoY74YtN4CIF5GuHAEnKqPoZBt5qYO2jur46q1OMEjvjtYATwNHMtD&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRgIhAPoXkJ5-MQTNCy19W1zJu8Hi8eo-eYw-5kH-AbFpAsuTAiEAi2EmxfUwfYtPlTQe0jWFVxc7yKMMz0Bqidcf2ZRvYU4="
},
"MP4_MEDIUM": {
"landscapeUri": "https://rr1---sn-p5qs7nzy.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZKvJBpnc-LYP8v6T-AM&ip=0.0.0.0&id=5f50000000000001&itag=374&source=aerial_view&mh=dX&mm=31&mn=sn-p5qs7nzy&ms=au&mv=D&mvi=1&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=25879743&dur=40.016&lmt=1683384621721411&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRQIhANzPUc2SwvlDZ-nyhxNfY8CGVjyitnfpS7MvbXb_f5kSAiAVArz85QjBBAZw-8ugFPIggKCO54IhR6xDg4rfJIh1Tw==&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgJJyNxWDuqLZ89X5wThN1IsVJyvyZ7Qw1Z4jqhCyahjgCIQD9hOjN3hDvX3CN5LiNkoLm-GGAuriUtv0PhtREc7yTVQ==",
"portraitUri": "https://rr5---sn-p5qlsn7s.googlevideo.com/videoplayback?expire=1683655708&ei=KIpaZJiuBo3g-LYPhtaG6AU&ip=0.0.0.0&id=9f50000000000001&itag=374&source=aerial_view&mh=D3&mm=31&mn=sn-p5qlsn7s&ms=au&mv=D&mvi=5&pl=0&susc=av&mime=video/mp4&vprv=1&gir=yes&clen=8228161&dur=40.016&lmt=1683384373331986&mt=1683654760&txp=0011224&sparams=expire,ei,ip,id,itag,source,susc,mime,vprv,gir,clen,dur,lmt&sig=AOq0QJ8wRQIgKsfEQB3GbLqYP5tmHwmkMVqVlfcNl7SBiuBqRw748VsCIQDgkwyNF4jOuOjoX5Qw6TgbpdIPhqS-EvCZ2g2JWPYpbw==&lsparams=mh,mm,mn,ms,mv,mvi,pl&lsig=AG3C_xAwRQIgHdDEnopIcI2jzLkRLOaKz8Cq1Pwm2yl3nJzaru1dBEsCIQCgor9bkMfAeULTq3EwjzCGjB_RvGBqhGfhJblbBloJpg=="
},
"HLS": {
"landscapeUri": "https://manifest.googlevideo.com/api/manifest/hls_variant/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/playlist_type/LIVE/sparams/expire,ei,ip,id,source,susc,vprv,itag,playlist_type/sig/AOq0QJ8wRgIhAKreaNNOkePt9uVonHcqKIXqUe0TQSA1fcI6BWJexJ2hAiEAv9cj6N9iXI0bH6Ke4fz4XWDtrxVCMgrkGijpsLMpvy8%3D/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRgIhAMbA_78Uc_HUS8LaVWnJB4Qg7ZKO5IZECuhldckmJ3hPAiEA-GR-0w1zuyFHpvaF1LZBuWgpUM55iosY0KF9MMsePDE%3D/file/index.m3u8",
"portraitUri": "https://manifest.googlevideo.com/api/manifest/hls_variant/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/playlist_type/LIVE/sparams/expire,ei,ip,id,source,susc,vprv,itag,playlist_type/sig/AOq0QJ8wRgIhAKreaNNOkePt9uVonHcqKIXqUe0TQSA1fcI6BWJexJ2hAiEAv9cj6N9iXI0bH6Ke4fz4XWDtrxVCMgrkGijpsLMpvy8%3D/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRgIhAMbA_78Uc_HUS8LaVWnJB4Qg7ZKO5IZECuhldckmJ3hPAiEA-GR-0w1zuyFHpvaF1LZBuWgpUM55iosY0KF9MMsePDE%3D/file/index.m3u8"
},
"DASH": {
"landscapeUri": "https://manifest.googlevideo.com/api/manifest/dash/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/sparams/expire,ei,ip,id,source,susc,vprv,itag/sig/AOq0QJ8wRAIgCClKKnnVXeNnUHirpyxkegs8XSw5bq5e2VHWu-2NGtkCIBvXoHxlfTVmIvB4F9mlxn9EnJxPrcPGo1yIrS-_zbBu/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRQIhAIU_a8wIuPfzMXy1selgJ1bRz1ffXm0YQeFshe0ijAzhAiAPzhkpOjm-IGubZ-Z7o3W_U7lAjR6OkEpWvNEFCRzUVg%3D%3D",
"portraitUri": "https://manifest.googlevideo.com/api/manifest/dash/expire/1682711042/ei/DSBMZM7qPPPh-LYP9ZWNmA8/ip/0.0.0.0/id/7fffffffffffffff/source/aerial_view/susc/av/playback_host/rr3---sn-aigzrnsz.googlevideo.com/mh/ap/mm/31/mn/sn-aigzrnsz/ms/au/mv/D/mvi/3/pl/0/vprv/1/pacing/0/mt/1682709203/itag/0/sparams/expire,ei,ip,id,source,susc,vprv,itag/sig/AOq0QJ8wRAIgCClKKnnVXeNnUHirpyxkegs8XSw5bq5e2VHWu-2NGtkCIBvXoHxlfTVmIvB4F9mlxn9EnJxPrcPGo1yIrS-_zbBu/lsparams/playback_host,mh,mm,mn,ms,mv,mvi,pl/lsig/AG3C_xAwRQIhAIU_a8wIuPfzMXy1selgJ1bRz1ffXm0YQeFshe0ijAzhAiAPzhkpOjm-IGubZ-Z7o3W_U7lAjR6OkEpWvNEFCRzUVg%3D%3D"
}
},
"state": "ACTIVE",
"metadata": {
"videoId": "-wVXGP6Hkogfqz6sZulUf3",
"captureDate": {
"year": 2022,
"month": 10,
"day": 24
},
"duration": "40s"
}
}
برای دسترسی به ویدیوها، باید دامنه های زیر را در لیست مجاز قرار دهید:
-
*.gstatic.com -
*.googlevideo.com
ویدیو پیدا نشد
بسته به در دسترس بودن یا نبودن تصاویر سه بعدی برای مکان، دو پاسخ احتمالی «ویدئو یافت نشد» وجود دارد.
ارائه نشده است
این ویدئو قبلا رندر نشده است و بنابراین هنوز در پایگاه داده گوگل نیست.
{
"error": {
"code": 404,
"message": "Video not found.",
"status": "NOT_FOUND"
}
}
بدون تصویر سه بعدی
Google قبلاً تلاش کرده بود ویدیو را ارائه کند، اما موفق نشد زیرا تصاویر سه بعدی برای آن آدرس در دسترس نیست.
{
"error": {
"code": 404,
"message": "Video not found: No 3d imagery.",
"status": "NOT_FOUND"
}
}
رندر در حال انجام است
سیستم همچنان در حال پردازش درخواست رندر شما است، همانطور که توسط state در حال تنظیم روی PROCESSING تعریف شده است. شما یک videoId دریافت می کنید که می توانید از آن برای دریافت ویدیو با تماس با lookupVideo استفاده کنید.
{
"state": "PROCESSING",
"metadata": {
"videoId": "u-zlVPiScvcD8BYmIVyxoF"
}
}
فرآیند رندر می تواند از یک ساعت تا چند ساعت طول بکشد. اگر ویدیو همچنان در حال پردازش است، می‌توانید از lookupVideo برای نظرسنجی از وضعیت ویدیو استفاده کنید تا زمانی که حالت ACTIVE برگردد.
برای نظرسنجی، با عبور از videoId ، درخواستی برای lookupVideo ارائه دهید. رندرینگ می‌تواند چندین ساعت طول بکشد، بنابراین برای فاصله گرفتن از تماس‌هایتان ، از عقب‌نشینی نمایی استفاده کنید.
درخواست مثال برای ارسال videoId
اگر با lookupVideo تماس گرفتید و متوجه شدید که هیچ ویدیوی نمای هوایی برای آدرس وجود ندارد، می توانید با آن آدرس renderVideo تماس بگیرید. renderVideo یک شی VideoMetadata را برمی‌گرداند که حاوی videoId است. بعداً می‌توانید از videoId ، به جای آدرس، برای دریافت ویدیو با ارسال آن به lookupVideo استفاده کنید.
مثال کد زیر نحوه فراخوانی lookupVideo را نشان می‌دهد و آن را به عنوان videoId ارسال می‌کند.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&videoId=VIDEO_ID "