با توجه به یک آدرس یا شناسه ویدیویی معتبر، روش lookupVideo
URI هایی را برمی گرداند که مجموعه ای از ویدیوهای Aerial View API را شناسایی می کنند. روش lookupVideo
تنها زمانی URI ها را برمی گرداند که Google قبلاً یک ویدیو برای آن مکان ایجاد کرده باشد.
برای بررسی وجود ویدیو، از روش lookupVideoMetadata
استفاده کنید.
نحوه استفاده از API
این نقطه پایانی را با ارسال یک آدرس پستی ایالات متحده کدگذاری شده با 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 "