جلب فيديو

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