جلب فيديو

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

  • إذا كان الفيديو متوفّرًا في نظامنا ولكن لم يتم عرضه بالكامل بعد، ستعرض lookupVideo حالة المعالجة PROCESSING، بالإضافة إلى videoId، التي يمكنك استخدامها للحصول على الفيديو بعد انتهاء عملية العرض.

  • إذا لم يكن الفيديو متوفّرًا بعد، ستعرض واجهة برمجة التطبيقات رمز الحالة 404. في هذه الحالة، يمكنك إنشاء فيديو جديد من خلال استدعاء renderVideo.

كيفية استخدام معرّفات الموارد الموحّدة للفيديوهات التي تم إرجاعها

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

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

توفير فيديوهات يسهل الوصول إليها

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

على سبيل المثال، أضِف وصفًا بالشكل التالي:

"هذه صورة جوية واقعية لـ ADDRESS مقدَّمة من "خرائط Google"."

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

"هذه صورة جوية واقعية لبرج إمباير ستيت في نيويورك مقدَّمة من "خرائط Google"."

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

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

مثال على طلب يتضمّن عنوانًا

يطلب نموذج الرمز البرمجي التالي فيديو لمنظر جوي لبرج 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"