כשנותנים כתובת או מזהה סרטון תקינים, ה-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 לרוחב ו-URI לאורך לכל סוג מדיה נתמך ומטא-נתונים נתמכים.אם הסרטון נמצא במערכת שלנו אבל עדיין לא עבר רינדור מלא, הפונקציה
lookupVideo
תחזיר את סטטוס העיבודPROCESSING
ו-videoId
, שאפשר להשתמש בו כדי לקבל את הסרטון אחרי שהרינדור יושלם.אם הסרטון עדיין לא קיים, ה-API יחזיר את קוד הסטטוס 404. במקרה כזה, ניתן ליצור סרטון חדש על ידי קריאה אל
renderVideo
.
איך משתמשים במזהי ה-URI של הסרטונים שמוחזרים
צריך לקרוא ל-method 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 "