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