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

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

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

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

هذا مثال على طلب

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