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

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

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

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

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

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