אחזור סרטון

בהינתן כתובת תקפה או מזהה סרטון תקף, ה-method‏ 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 לזמן קצר והתוקף שלהן פג אחרי זמן קצר.

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

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

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

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

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

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

"This is a photorealistic aerial view of the Empire State Building in New York provided by Google Maps.‎"

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

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

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

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

כדי לבצע שאילתת Poll, שולחים בקשה אל 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"