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

جلب فيديو

عند تحديد عنوان أو معرّف فيديو صالح، تعرض الطريقة lookupVideo معرّفات URI لتحديد مجموعة من فيديوهات Aerial View API. لا تعرض الطريقة lookupVideo معرّفات الموارد المنتظِمة إلا عندما يكون محرّك بحث 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". وبالتالي يمكنك تخزين قيم معرّف الفيديو لاستخدامها لاحقًا.

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

يطلب نموذج التعليمة البرمجية التالي فيديو عرض جوي لهرم 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.

تم العثور على الفيديو

إذا كان الفيديو الذي تطلبه متوفرًا، تعرض واجهة برمجة التطبيقات قائمة بمعرّفات الموارد المنتظمة (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"