طلب صورة التجوّل الافتراضي هو عنوان 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 أو لم تظهر أي قيمة،
هذا يعني أنّه تم حذف رقم تعريف البانوراما ويجب إعادة تحميله.
احفظ عنوان الموقع أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على معرّف بانوراما حتى تتمكن من التحديث عند الحاجة.
عند اكتشاف تغيير معرف البانوراما، استخدم عنوان الموقع الأصلي أو إحداثيات خط العرض وخط الطول للبحث مرة أخرى عن أقرب صور بانورامية لهذا الموقع والحصول على معرّف بانوراما جديد.
المعلمات الاختيارية
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 BAD REQUEST). القيمتان الصالحتان هماtrueوfalse. في حال ضبط هذه السياسة علىtrue، يتم عرض رسالة خطأ بدلاً من الصورة الرمادية العامة. يغنيك ذلك عن الحاجة إلى إجراء مكالمة منفصلة للتحقّق من توفّر الصور. source(القيمة التلقائية هيdefault) تقتصر عمليات البحث في "التجوّل الافتراضي" على المصادر المحدّدة. القيم الصالحة هي:- يستخدم
defaultالمصادر التلقائية لميزة "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر معيّنة. - تقتصر عمليات البحث على المجموعات في الأماكن الخارجية من خلال "
outdoor". لا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّه قد لا تتوفّر صور بانورامية خارجية للموقع الجغرافي المحدّد. يُرجى العِلم أيضًا أنّ عملية البحث تعرض صور بانورامية فقط حيث يمكن تحديد ما إذا كانت هذه الصور داخل المنزل أو في الهواء الطلق. على سبيل المثال، لا يتم عرض صور بانوراما 360 درجة لأنّه لا يُعرف ما إذا كانت داخلية أم في الهواء الطلق.
- يستخدم
هذا مثال على طلب.
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 لم يتم العثور" بدلاً من الصورة الرمادية العامة، في حال عدم توفّر أي صورة للموقع المحدد. - طلب البيانات الوصفية لصور "التجوّل الافتراضي" لتحديد ما إذا كانت هناك صور متاحة للموقع الجغرافي المحدّد قبل إرسال الطلب