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