تمت ترجمة هذه الصفحة بواسطة 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 Maps Platform. وبالتالي، يمكنك تخزين قيم معرّفات الفيديو لاستخدامها في وقت لاحق.

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

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