طلب "التجوّل الافتراضي" والرد عليه

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

إعادة تحميل أرقام تعريف الصور البانورامية المحذوفة

إذا حاولت استرداد معرّف بانوراما وظهرت لك القيمة ZERO_RESULTS أو no، هذا يعني أنّه تم حذف معرّف البانوراما ويجب إعادة تحميل الصفحة.

1. احفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على رقم تعريف بانورامي حتى تتمكّن من إعادة تحميل البيانات عند الحاجة.

2. عند رصد تغيير في معرّف بانوراما، استخدِم عنوان الموقع الجغرافي الأصلي أو إحداثيات خطوط الطول والعرض للبحث مرة أخرى عن أقرب مناظر بانورامية إلى هذا الموقع الجغرافي والحصول على معرّف بانوراما جديد.

المعلمات الاختيارية

• ‫signature (مُقترَح) هي توقيع رقمي يُستخدَم للتحقّق من أنّ أي موقع إلكتروني يُنشئ طلبات باستخدام مفتاح واجهة برمجة التطبيقات لديه إذن للقيام بذلك. وقد لا تنجح الطلبات التي لا تتضمّن توقيعًا رقميًا. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.

  ملاحظة: بالنسبة إلى عملاء الخطة المميّزة السابقة في Google Maps Platform، يجب تقديم توقيع digial . يمكنك الحصول على مزيد من المعلومات عن مَعلمات المصادقة لعملاء خطة 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 تحدّ من عمليات البحث على المجموعات الخارجية. لا يتم تضمين مجموعات الفعاليات المغلقة في نتائج البحث. يُرجى العِلم أنّه قد لا تتوفّر صور بانورامية في الهواء الطلق للموقع الجغرافي المحدّد. يُرجى العلم أيضًا أنّ البحث لا يعرض سوى الصور البانورامية التي يمكن تحديد ما إذا كانت داخلية أو خارجية. على سبيل المثال، لا يتم عرض صور بانورامية 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

لا تتوفّر صور

بالنسبة إلى المواقع الجغرافية التي لا تتوفّر فيها صور "التجوّل الافتراضي"، تعرض واجهة برمجة التطبيقات لميزة "التجوّل الافتراضي" static API صورة عامة رمادية تتضمّن النص "نعتذر، لا تتوفّر لدينا صور هنا"، كما هو موضّح في هذا المثال:

عرض الصور الصالحة فقط

لتجنُّب عرض الصورة العامة والتأكّد من أنّ صفحة الويب لا تعرض سوى صور Street View Static API الصالحة، اتّبِع الخطوات التالية:

• اضبط المَعلمة return_error_code على true. يؤدي ذلك إلى عرض واجهة برمجة التطبيقات Street View Static API لخطأ 404 (لم يتم العثور عليه) بدلاً من الصورة الرمادية العامة، إذا لم تكن هناك صورة متاحة للموقع الجغرافي المحدّد.
• يمكنك طلب البيانات الوصفية لصور "التجوّل الافتراضي" لتحديد ما إذا كانت هناك صور متاحة للموقع الجغرافي المحدّد قبل إرسال طلب.