یک ویدیو واکشی کنید

با توجه به یک آدرس یا شناسه ویدیویی معتبر، متد lookupVideo آدرس‌های اینترنتی (URI) را که مجموعه‌ای از ویدیوهای API نمای هوایی (Aerial View) را شناسایی می‌کنند، برمی‌گرداند. متد lookupVideo فقط زمانی URIها را برمی‌گرداند که گوگل قبلاً ویدیویی برای آن مکان تولید کرده باشد.

برای بررسی وجود یک ویدیو، از متد 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 کد وضعیت ۴۰۴ را برمی‌گرداند. در این حالت، می‌توانید با فراخوانی renderVideo یک ویدیوی جدید تولید کنید .

نحوه استفاده از URI های ویدیویی برگردانده شده

متد lookupVideo را به ازای هر آدرس یا videoID به ازای هر نما یک بار فراخوانی کنید. URI های ویدئو در پاسخ، URI های کوتاه مدت نامیده می‌شوند و پس از مدت کوتاهی منقضی می‌شوند.

گوگل مرتباً ویدیوها را به‌روزرسانی می‌کند. بنابراین، برای اطمینان از اینکه جدیدترین محتوا را به مشتریان خود نمایش می‌دهید، هر بار که ویدیویی را نمایش می‌دهید، متد lookupVideo را فراخوانی کنید.

پشتیبانی از ویدیوهای قابل دسترس

برای پشتیبانی از دسترسی‌پذیری، گوگل توصیه می‌کند هنگام نمایش یک ویدیوی هوایی به مشتریان خود، متن یا توضیحات ویدیو را اضافه کنید. به این ترتیب، یک صفحه‌خوان می‌تواند متن یا توضیحات آن را به کاربر اعلام کند.

برای مثال، توضیحی را در فرم اضافه کنید:

«این یک نمای هوایی واقع‌گرایانه از آدرس است که توسط گوگل مپس ارائه شده است.»

به جای آدرس، می‌توانید توضیحی از ویدیو به شکل زیر اضافه کنید:

«این یک نمای هوایی واقع‌گرایانه از ساختمان امپایر استیت در نیویورک است که توسط گوگل مپس ارائه شده است.»

ذخیره شناسه‌های ویدیو برای استفاده‌های بعدی

با توجه به شرایط خاص سرویس برای Aerial View API، شناسه‌های ویدیویی Aerial View API از محدودیت‌های ذخیره‌سازی ذکر شده در بخش 3.2.3(b)(بدون ذخیره‌سازی) از شرایط خدمات پلتفرم Google Maps معاف هستند. بنابراین می‌توانید مقادیر شناسه ویدیویی را برای استفاده‌های بعدی ذخیره کنید.

مثال درخواست ارسال آدرس

نمونه کد زیر، یک ویدیوی نمای هوایی از هرم ترانس آمریکا، واقع در خیابان مونتگومری ۶۰۰، سانفرانسیسکو، کالیفرنیا ۹۴۱۱۱، درخواست می‌کند.

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"
  }
}

بدون تصویر سه بعدی

گوگل قبلاً تلاش کرده بود تا این ویدیو را رندر کند، اما به دلیل عدم وجود تصاویر سه‌بعدی برای آن آدرس، موفق نشد.

{
  "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 استفاده کنید.

برای نظرسنجی، درخواستی به lookupVideo ارسال کنید و videoId را ارسال کنید. رندر کردن می‌تواند چندین ساعت طول بکشد، بنابراین از backoff نمایی برای فاصله‌گذاری بین فراخوانی‌های خود استفاده کنید.

درخواست نمونه برای ارسال 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"