تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

جلب فيديو

عند تحديد عنوان أو معرّف فيديو صالحَين، تعرض الطريقة lookupVideo معرّفات URI تحدّد مجموعة من فيديوهات 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) أفقي وعمودي لكل نوع وسائط متوافق، بالإضافة إلى البيانات الوصفية.

ملاحظة: لا تتم فوترة المكالمات إلى نقطة النهاية هذه إلا عند توفُّر فيديو وعرض معرّف موارد منتظم (URI) للفيديو.
إذا كان الفيديو في نظامنا ولكن لم يتم عرضه بالكامل إلى الآن، تعرض حالة المعالجة lookupVideo حالة المعالجة PROCESSING، وتعرض videoId، التي يمكنك استخدامها لعرض الفيديو بعد اكتمال عرضه.
إذا لم يكن الفيديو متوفرًا بعد، ستعرض واجهة برمجة التطبيقات رمز الحالة 404. في هذه الحالة، يمكنك إنشاء فيديو جديد من خلال الاتصال بالرمز renderVideo.

كيفية استخدام معرّفات الموارد المنتظمة (URI) للفيديو المعروضة

عليك طلب طريقة lookupVideo مرة واحدة لكل عنوان أو videoID لكل مشاهدة. يُشار إلى معرّفات الموارد المنتظمة (URI) للفيديو في الاستجابة باسم معرّفات الموارد المنتظمة (URI) القصيرة الأجل وتنتهي صلاحيتها بعد فترة قصيرة.

تعدّل Google الفيديوهات بشكل متكرّر. لذلك، لضمان عرض أحدث محتوى لعملائك، اتصل بطريقة lookupVideo في كل مرة تعرض فيها فيديو.

دعم الفيديوهات التي يمكن الوصول إليها

لإتاحة إمكانية الوصول، تنصح Google بإضافة نص أو وصف فيديو عند عرض فيديو عرض جوي لعملائك. بهذه الطريقة، يمكن لقارئ الشاشة إعلان النص أو وصفه للمستخدم.

على سبيل المثال، أضِف وصفًا في النموذج:

"هذا منظر جوي واقعي لـ ADDRESS تم تقديمه في "خرائط Google"."

وبدلاً من إضافة عنوان، يمكنك إضافة وصف للفيديو على النحو التالي:

"هذا منظر جوي واقعي لمبنى إمباير ستيت في نيويورك من خلال خرائط Google".

حفظ معرّفات الفيديوهات لاستخدامها لاحقًا

وفقًا للبنود الخاصة بالخدمة لواجهة برمجة تطبيقات Aerial View API، يتم إعفاء معرّفات الفيديوهات من Aerial View API من قيود التخزين المؤقت المنصوص عليها في الفقرة 3.2.3(ب)(عدم التخزين المؤقت) من بنود خدمة "منصة خرائط Google". وبالتالي، يمكنك تخزين قيم معرّف الفيديو لاستخدامها في وقت لاحق.

مثال على طلب تمرير عنوان

يتطلب نموذج التعليمة البرمجية التالي فيديو عرض جوي لهرم ترانس أمريكا ال، الواقع في 600 شارع مونتغمري، سان فرانسيسكو، كاليفورنيا 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"