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