דף זה תורגם על ידי Cloud Translation API.

אחזור סרטון

אם מזינים כתובת או מזהה וידאו תקינים, ה-method lookupVideo מחזירה מזהי URI שמזהים קבוצה של סרטונים ב-Aerial View API. ה-method 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 לרוחב ו-URI לאורך לכל סוג מדיה נתמך ומטא-נתונים נתמכים.

הערה: החיוב על שיחות לנקודת הקצה הזו מתבצע רק כשקיים סרטון ומוחזר URI של וידאו.
אם הסרטון נמצא במערכת שלנו אבל הוא עדיין לא עבר עיבוד מלא, lookupVideo יחזיר מצב עיבוד של PROCESSING ו-videoId, שבו תוכלו להשתמש כדי לקבל את הסרטון בסיום הרינדור.
אם הסרטון עדיין לא קיים, ה-API יחזיר קוד סטטוס 404. במקרה כזה, ניתן ליצור סרטון חדש על ידי קריאה אל renderVideo.

כיצד להשתמש במזהי ה-URI של הסרטונים שהוחזרו

מפעילים את השיטה lookupVideo פעם אחת לכל כתובת או videoID לכל תצוגה מפורטת. מזהי ה-URI של הסרטונים בתגובה מכונים מזהי URI לטווח קצר והתוקף שלהם פג לאחר זמן קצר.

Google מעדכנת את הסרטונים לעיתים קרובות. לכן, כדי לוודא שאתם מציגים ללקוחות את התוכן העדכני ביותר, צריך להפעיל את השיטה lookupVideo בכל פעם שאתם מציגים סרטון.

תמיכה בסרטונים נגישים

כדי לתמוך בנגישות, Google ממליצה להוסיף תמליל או תיאור סרטון כשמציגים ללקוחות סרטון בתצוגה אווירית. כך, קורא מסך יכול להקריא למשתמש את התמליל או את התיאור שלו.

לדוגמה, מוסיפים תיאור בטופס:

"זוהי צילום אווירי ריאליסטי של ADDRESS שסופק על ידי מפות Google."

במקום כתובת, אפשר להוסיף תיאור של הסרטון בטופס:

"זוהי צילום אווירי פוטוריאליסטי של בניין האמפייר סטייט בניו יורק, שסופק על ידי מפות Google".

שמירת מזהי סרטונים לשימוש במועד מאוחר יותר

בכפוף לתנאים הספציפיים לשירות של Aerial View API, מזהי וידאו של Aerial View API פטורים מהגבלות השמירה במטמון שמפורטות בסעיף 3.2.3(ב)(ללא שמירה במטמון) של התנאים וההגבלות של הפלטפורמה של מפות Google. לכן תוכלו לאחסן ערכים של מזהה וידאו לשימוש מאוחר יותר.

דוגמה לבקשה שמעבירה כתובת

דוגמת הקוד הבאה מבקשת סרטון תצוגה אווירית עבור הפירמידה של 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

הסרטון לא נמצא

יש שתי תגובות אפשריות מסוג "לא נמצא סרטון", בהתאם לשאלה אם יש תמונות תלת-ממדיות במיקום הזה או לא.

לא עבר רינדור

הסרטון לא עבר עיבוד בעבר, ולכן הוא עדיין לא נמצא במסד הנתונים של Google.

{
  "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.

כדי להשתתף בסקר, צריך לשלוח בקשה לצוות של lookupVideo ולהעביר את videoId. העיבוד עשוי להימשך כמה שעות, לכן כדאי להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential 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"