عند تقديم عنوان أو معرّف فيديو صالحَين، تعرض الطريقة
lookupVideo
معرّفات الموارد المنتظمة التي تحدّد مجموعة من الفيديوهات في Aerial View API. لا تعرض الطريقة lookupVideo
معرّفات الموارد المنتظمة (URI) إلا إذا سبق أن أنشئ محرّك بحث Google فيديو
لذلك الموقع الجغرافي.
للتحقّق مما إذا كان الفيديو متوفّرًا، استخدِم الرمز التالي:
lookupVideoMetadata
.
كيفية استخدام واجهة برمجة التطبيقات
استدعِ نقطة النهاية هذه من خلال اختيار عنوان بريد إلكتروني بترميز عنوان URL في الولايات المتحدة أو videoId
.
curl -X GET "https://aerialview.googleapis.com/v1/videos:lookupVideo?key=YOUR_API_KEY&address=POSTAL_ADDRESS "
بعد ذلك، تعرض واجهة برمجة التطبيقات أحد الردود الثلاثة التالية:
في حال توفُّر فيديو، يعرض
lookupVideo
حالة المعالجةACTIVE
، ومعرّف موارد منتظم (URI) أفقي ورأسي لكل نوع وسائط متوافق وبيانات وصفية.إذا كان الفيديو في نظامنا ولكن لم يتم عرض محتواه بالكامل بعد، يعرض
lookupVideo
حالة المعالجةPROCESSING
وvideoId
، ويمكنك استخدامهما للحصول على الفيديو بعد انتهاء عرض محتواه.إذا لم يكن الفيديو متوفّرًا بعد، ستعرِض واجهة برمجة التطبيقات رمز الحالة 404. في هذه الحالة، يمكنك إنشاء فيديو جديد من خلال الاتصال بالرقم
renderVideo
.
كيفية استخدام عناوين URL التي تم عرضها للفيديو
وعليك استدعاء الطريقة lookupVideo
مرة واحدة لكل عنوان أو videoID
لكل طريقة عرض. يُشار إلى عناوين URI
للفيديوهات في الردّ باسم عناوين URI صالحة لفترة قصيرة وتنتهي صلاحيتها بعد
فترة قصيرة.
تعدّل Google الفيديوهات بشكل متكرّر. لذلك، لضمان
عرض أحدث المحتوى على عملائك، استخدِم الأسلوب lookupVideo
في كل مرة تعرض فيها فيديو.
إتاحة الفيديوهات للوصول إليها
لإتاحة إمكانية الوصول، تنصح Google بإضافة نص أو وصف فيديو عند عرض فيديو تصوير جوّي أمام عملائك. بهذه الطريقة، يمكن لقارئ الشاشة قراءة النص أو وصفه للمستخدم.
على سبيل المثال، أضِف وصفًا في النموذج:
"هذا عرض جوي واقعي لـ ADDRESS من خلال خرائط Google".
بدلاً من عنوان، يمكنك إضافة وصف للفيديو على النحو التالي:
"هذه صورة جوية واقعية لمبنى إمباير ستيت في نيويورك، وقد زوّدتها "خرائط Google"."
حفظ أرقام تعريف الفيديوهات لاستخدامها لاحقًا
يخضع معرّفات الفيديوهات في Aerial View API للإعفاء من القيود المفروضة على التخزين المؤقت والمذكورة في الفقرة 3.2.3(ب)(عدم التخزين المؤقت) من بنود خدمة Google Maps Platform، وذلك بموجب "الأحكام الخاصة بالخدمة" لواجهة برمجة التطبيقات Aerial View API. وبالتالي، يمكنك تخزين قيم معرّفات الفيديو لاستخدامها في وقت لاحق.
مثال على طلب يُرسل عنوانًا
يطلب نموذج الرمز البرمجي التالي فيديو يعرض منظرًا جويًا لمبنى Transamerica Pyramid الواقع في 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
.
تم العثور على الفيديو
إذا كان الفيديو الذي تطلبه متوفرًا، تعرض واجهة برمجة التطبيقات قائمة بمعرّفات الموارد المنتظمة (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
. يمكن أن يستغرق التقديم
عدة ساعات، لذا استخدِم
الوقت المتزايد
لإبقاء فترات بين طلباتك.
مثال على طلب يُرسل 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 "