طلب "التجوّل الافتراضي" والرد عليه

طلب صورة "التجوّل الافتراضي" هو عنوان URL يستخدم HTTP بالتنسيق التالي:

https://maps.googleapis.com/maps/api/streetview?parameters

يتم تحديد الصورة باستخدام مَعلمات الطلب. وكما هو الحال في عناوين URL، يتم فصل جميع المعلمات باستخدام حرف العطف (&). في ما يلي المَعلمات المسموح بها وقيمها المحتملة.

المعلمات المطلوبة

يمكنك تنفيذ أحد الإجراءين التاليين:

  • يمكن أن يكون location سلسلة نصية (مثل Chagrin Falls, OH) أو زوجًا من إحداثيات خط الطول وخط العرض (40.457375,-80.009353)، ويجب أن يكون بترميز عنوان URL. لذلك قم بتحويل عناوين مثل "سيتي هول، نيويورك، نيويورك" إلى "سيتي + هول،نيو+يورك، نيويورك" قبل إرسال الطلب. تتم إضافة واجهة برمجة تطبيقات "التجوّل الافتراضي" الثابتة إلى الصورة البانورامية الأقرب إلى الموقع. عند تقديم سلسلة نصية للعنوان، قد تستخدم واجهة برمجة التطبيقات موقعًا مختلفًا للكاميرا من أجل عرض الموقع الجغرافي المحدّد بشكل أفضل. عند تقديم إحداثيات خطي الطول والعرض، تبحث واجهة برمجة التطبيقات في نصف قطر 50 متر عن صورة أقرب إلى الموقع. نظرًا لأنه يتم تحديث صور "التجوّل الافتراضي" بشكل دوري، وقد يتم التقاط الصور الفوتوغرافية من مواضع مختلفة قليلاً في كل مرة، ومن الممكن أن يلتقط location صورة بانوراما مختلفة عند تعديل الصور.

أو الصيغة التالية:

  • pano هو معرّف بانوراما محدد. قد تغير الصور البانورامية رقم التعريف بمرور الوقت، لذا لا تحتفظ برقم التعريف هذا. بدلاً من ذلك، احفظ عنوان الموقع أو إحداثيات خط العرض وخط الطول حتى تتمكن من تحديث معرف البانوراما. للحصول على التفاصيل، يمكنك الاطّلاع على إعادة تحميل معرّفات الصور البانورامية المحذوفة.

بالإضافة إلى:

  • تحدّد size حجم إخراج الصورة بالبكسل. يتم تحديد الحجم على النحو التالي: {width}x{height} - على سبيل المثال، يعرض size=600x400 صورة بعرض 600 بكسل وارتفاع 400 بكسل.
  • يتيح لك key مراقبة استخدام تطبيقك لواجهة برمجة التطبيقات في Google Cloud Console، وتضمن إمكانية تواصل Google معك بشأن تطبيقك إذا لزم الأمر. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.

إعادة تحميل معرّفات الصور البانورامية المحذوفة

إذا حاولت استرداد معرّف بانوراما والحصول على ZERO_RESULTS أو لا قيمة، يعني ذلك أنّه قد تم حذف معرّف البانوراما ويجب تحديثه.

  1. احفظ عنوان الموقع أو إحداثيات خطي الطول والعرض التي استخدمتها للحصول على معرف بانوراما حتى تتمكن من إعادة التحميل عند الحاجة.

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

المعلمات الاختيارية

  • signature (يُنصح به) هو توقيع رقمي يُستخدم للتحقق من أنّ أي طلبات تنشئ موقعًا إلكترونيًا باستخدام مفتاح واجهة برمجة التطبيقات قد يُسمح لها بإجراء ذلك. وقد يتعذّر تنفيذ الطلبات التي لا تتضمّن توقيعًا رقميًا. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.

    ملاحظة: بالنسبة إلى العملاء السابقين في الخطة المميّزة لمنصة خرائط Google، يجب التوقيع الرقمي. يمكنك الحصول على مزيد من المعلومات عن مَعلمات المصادقة لعملاء الخطة المميّزة.

  • تشير العلامة heading إلى اتجاه بوصلة الكاميرا. تتراوح القيم المقبولة بين 0 و360 (تشير كلتا القيمتَين إلى الشمال، بينما تشير القيمة 90 إلى الشرق، و180 باتجاه الجنوب). إذا لم تحدّد عنوانًا، يتم احتساب قيمة توجّه الكاميرا نحو location المحدّد، بدءًا من النقطة التي تم فيها التقاط أقرب صورة.
  • fov (القيمة التلقائية هي 90) تحدد حقل العرض الأفقي للصورة المعبّرة بالدرجات، مع الحد الأقصى المسموح به للقيمة وهو 120. عند التعامل مع إطار عرض بحجم ثابت، كما هو الحال مع صورة "التجوّل الافتراضي" ذات حجم محدَّد، يمثّل مجال الرؤية في الواقع التكبير أو التصغير، بينما تشير الأرقام الأصغر إلى مستوى أعلى من التكبير أو التصغير.


    لقطة شاشة لمجال رؤية واسع النطاق تُظهر السقف والجدران والأرضية ونافذة حوض داخل حوض سمك. لقطة شاشة لمجال رؤية ذي لقطة مقرّبة، تُظهر تفاصيل مصغَّرة لصورة "التجوّل الافتراضي" داخل حوض سمك.
    (يسار: fov=120، يمين: fov=20)

  • pitch (القيمة التلقائية هي 0) تحدّد الزاوية العلوية أو السفلية للكاميرا المتعلقة بمركبة "التجوّل الافتراضي". ويكون هذا الوضع أفقيًّا مسطّحًا في كثير من الأحيان، ولكن ليس دائمًا. أمّا القيم الموجبة، فتجعل زاوية الكاميرا للأعلى (وتشير الزاوية 90 إلى الأعلى مباشرةً)، أمّا القيم السالبة، فتجعل زاوية الكاميرا لأسفل (وتشير القيمة -90 إلى أسفلها مباشرةً).
  • radius (القيمة التلقائية هي 50) لضبط نصف قطر محدد بالمتر، والذي يمكن البحث فيه عن صورة بانورامية، في مركز على خط العرض وخط الطول المحدّدَين. والقيم الصالحة هي أعداد صحيحة غير سالبة.
  • تشير السمة return_error_code إلى ما إذا كان يجب أن تعرض واجهة برمجة التطبيقات رمز خطأ في حال عدم العثور على صورة (خطأ 404 لم يتم العثور عليه) أو استجابةً لطلب غير صالح (400 طلب غير صالح). القيمتان الصالحتان هما true وfalse. في حال ضبط السياسة على true، سيتم عرض رسالة خطأ بدلاً من الصورة الرمادية العامة. بهذه الطريقة، لن تحتاج إلى إجراء مكالمة منفصلة للتحقّق من توفّر الصور.
  • source (القيمة التلقائية هي default) تقصِر عمليات البحث في "التجوّل الافتراضي" على المصادر المحدَّدة. في ما يلي القيم الصالحة:
    • يستخدم default المصادر التلقائية لميزة "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر معيّنة.
    • تقتصر عمليات البحث على outdoor في المجموعات الخارجية. ولا يتم تضمين المجموعات الداخلية في نتائج البحث. تجدر الإشارة إلى أنّ صور البانوراما الخارجية قد لا تكون موجودة للموقع الجغرافي المحدد. يُرجى العِلم أيضًا أنّ البحث لا يعرض سوى الصور البانورامية التي يكون من الممكن تحديد ما إذا كانت داخلية أو في الهواء الطلق. على سبيل المثال، لا يتم إرجاع الصور التي تم التقاطها في الداخل أو في الهواء الطلق لأنّه غير معروف.

هذا مثال على الطلب.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
لقطة شاشة لصورة من نقطة مشاهدة على مستوى الشارع تظهر فيها خطوط سكك حديدية كهربائية.

لا تتوفر أي صور

بالنسبة إلى المواقع الجغرافية التي لا تتوفر فيها صور "التجوّل الافتراضي"، تعرض واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" صورة عامة رمادية تتضمن النص "عذرًا، لا تتوفّر لدينا أي صور هنا"، كما هو موضح في هذا المثال:

لقطة شاشة للصورة العامة التي يتم عرضها عندما لا تتوفر أي صور للموقع الجغرافي المحدّد الخلفية باللون البني الفاتح، وتعرض النص المكتوب "عذرًا، ليست لدينا أي صور هنا".
الشكل: صورة عامة يتم عرضها عندما لا تتوفر أي صور للموقع الجغرافي المحدّد.

عرض الصور الصالحة فقط

لتجنّب عرض الصورة العامة والتأكّد من أنّ صفحة الويب تعرض فقط صور "التجوّل الافتراضي" الثابتة والصالحة فقط، اتّبِع الاقتراحات التالية:

  • اضبط المَعلمة return_error_code على true. يؤدي هذا إلى عرض واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" للخطأ 404 لم يتم العثور عليه بدلاً من الصورة الرمادية العامة، وذلك في حال عدم توفر أي صورة للموقع المحدد.
  • اطلب البيانات الوصفية لصور "التجوّل الافتراضي" لتحديد ما إذا كانت هناك صور متاحة للموقع الجغرافي المحدّد قبل إرسال الطلب.