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

طلب صورة التجوّل الافتراضي هو عنوان 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 Maps Platform، يجب التوقيع الرقمي. اطّلِع على مزيد من المعلومات عن معلّمات المصادقة لعملاء خطة 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

لا صور متاحة

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

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

لتجنب عرض الصورة العامة، والتأكد من أن صفحة الويب تعرض فقط صورًا ثابتة صالحة لواجهة برمجة التطبيقات للتجوّل الافتراضي، اتبع هذه الاقتراحات:

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