طلب صورة "التجوّل الافتراضي" هو عنوان URL يستخدم HTTP بالتنسيق التالي:
https://maps.googleapis.com/maps/api/streetview?parameters
يتم تحديد الصورة باستخدام مَعلمات الطلب. وكما هو معتاد في عناوين URL، يتم فصل جميع المَعلمات باستخدام رمز العطف اللاتيني (&). في ما يلي المَعلمات المسموح بها وقيمها المحتملة.
المعلمات المطلوبة
يمكنك إجراء ذلك بإحدى طريقتين:
- يمكن أن تكون السمة
locationإما سلسلة نصية (مثلChagrin Falls, OH) أو زوجًا من إحداثيات خطوط العرض والطول (40.457375,-80.009353)، ويجب أن تكون مشفّرة باستخدام عنوان URL. لذلك، عليك تحويل العناوين مثل "City Hall, New York, NY" إلى "City+Hall,New+York,NY" قبل إرسال الطلب. تنتقل واجهة برمجة التطبيقات Street View Static API إلى صورة التجوّل الافتراضي الأقرب إلى الموقع الجغرافي. عند تقديم سلسلة نصية للعنوان، قد تستخدم واجهة برمجة التطبيقات موقعًا جغرافيًا مختلفًا للكاميرا لعرض الموقع الجغرافي المحدّد بشكل أفضل. عند تقديم إحداثيات خطوط العرض والطول، تبحث واجهة برمجة التطبيقات في نطاق 50 مترًا عن صورة أقرب إلى الموقع الجغرافي. بما أنّه يتم تحديث صور "التجوّل الافتراضي" بشكل دوري، وقد يتم التقاط الصور من مواضع مختلفة قليلاً في كل مرة، من المحتمل أن يتم تثبيتlocationعلى صورة بانورامية مختلفة عند تحديث الصور.
أو:
-
panoهو معرّف بانوراما محدّد. قد يتغيّر معرّف الصور البانورامية بمرور الوقت، لذا لا تحتفظ بهذا المعرّف. بدلاً من ذلك، يمكنك حفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول لتتمكّن من إعادة تحميل معرّف الصورة البانورامية. لمعرفة التفاصيل، يُرجى الاطّلاع على إعادة تحميل أرقام تعريف الصور البانورامية المحذوفة.
بالإضافة إلى:
- تحدّد السمة
sizeحجم الصورة الناتج بالبكسل. يتم تحديد الحجم على النحو التالي:{width}x{height}- على سبيل المثال، تعرض السمةsize=600x400صورة بعرض 600 بكسل وارتفاع 400 بكسل. - يتيح لك
keyمراقبة استخدام تطبيقك لواجهة برمجة التطبيقات في وحدة تحكّم Google Cloud، ويضمن أن تتمكّن Google من التواصل معك بشأن تطبيقك إذا لزم الأمر. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.
إعادة تحميل معرّفات الصور البانورامية المحذوفة
إذا حاولت استرداد معرّف بانوراما وحصلت على ZERO_RESULTS أو
لم تحصل على أي قيمة، يعني ذلك أنّه تم حذف معرّف البانوراما ويجب إعادة تحميله.
احفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على معرّف بانوراما حتى تتمكّن من إعادة التحميل عند الحاجة.
عند اكتشاف تغيير في معرّف بانوراما، استخدِم عنوان الموقع الجغرافي الأصلي أو إحداثيات خط العرض وخط الطول للبحث مرة أخرى عن أقرب صور بانورامية لهذا الموقع الجغرافي والحصول على معرّف بانوراما جديد.
المعلمات الاختيارية
signature(يُنصح به) هو توقيع رقمي يُستخدَم للتحقّق من أنّ أي موقع إلكتروني يُنشئ طلبات باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك لديه الإذن بذلك. قد يتعذّر تنفيذ الطلبات التي لا تتضمّن توقيعًا رقميًا. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.ملاحظة: بالنسبة إلى عملاء "الخطة المميّزة" السابقين في "منصة خرائط Google"، يجب استخدام التوقيع الرقمي. يمكنك الحصول على مزيد من المعلومات حول مَعلمات المصادقة لعملاء خطة Premium.
- يشير
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" على المجموعات الخارجية. ولا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّ الصور البانورامية الخارجية قد لا تكون متوفّرة للموقع الجغرافي المحدّد. يُرجى العِلم أيضًا أنّ البحث يعرض فقط الصور البانورامية التي يمكن تحديد ما إذا كانت داخلية أو خارجية. على سبيل المثال، لا يتم عرض صور PhotoSpheres لأنّه من غير المعروف ما إذا كانت داخلية أو خارجية.
- يستخدم
هذا مثال على الطلب.
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
لا تتوفّر صور
بالنسبة إلى المواقع الجغرافية التي لا تتوفّر فيها صور "التجوّل الافتراضي"، تعرض Street View Static API صورة عامة رمادية مع النص "عذرًا، لا تتوفّر لدينا صور هنا"، كما هو موضّح في هذا المثال:
عرض الصور الصالحة فقط
لتجنُّب عرض الصورة العامة والتأكّد من أنّ صفحة الويب تعرض فقط صورًا صالحة من Street View Static API، اتّبِع الاقتراحات التالية:
- اضبط مَعلمة
return_error_codeعلىtrue. يؤدي ذلك إلى عرض واجهة برمجة التطبيقات Street View Static API لخطأ 404 لم يتم العثور على الصفحة بدلاً من الصورة الرمادية العامة، في حال عدم توفّر صورة للموقع الجغرافي المحدّد. - اطلب البيانات الوصفية لصور "التجوّل الافتراضي" لتحديد ما إذا كانت هناك صور متاحة للموقع الجغرافي المحدّد قبل إرسال طلب.