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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

    ملاحظة: بالنسبة إلى عملاء "خطة Premium" السابقة في 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 NOT FOUND)، أو استجابةً لطلب غير صالح (400 BAD REQUEST). القيم الصالحة هي true وfalse. إذا تم ضبطها على true، سيتم عرض رسالة خطأ بدلاً من الصورة الرمادية العامة. ويؤدي ذلك إلى إلغاء الحاجة إلى إجراء طلب منفصل للتحقّق من توفّر الصورة.
  • يقتصر البحث في "التجوّل الافتراضي" على المصادر المحدّدة source (الإعداد التلقائي هو default). القيم الصالحة هي:
    • تستخدم default المصادر التلقائية لـ "التجوّل الافتراضي"، ولا تقتصر عمليات البحث على مصادر معيّنة.
    • يقتصر البحث في outdoor على المجموعات الخارجية. لا يتم تضمين المجموعات الداخلية في نتائج البحث. يُرجى العِلم أنّه قد لا تتوفّر صور بانورامية خارجية للموقع الجغرافي المحدّد. يُرجى العِلم أيضًا أنّ البحث لا يعرض سوى الصور البانورامية التي يمكن تحديد ما إذا كانت في مكان داخلي أو خارجي. على سبيل المثال، لا يتم عرض صور Photo Sphere لأنّه من غير المعروف ما إذا كانت في مكان مغلق أو مفتوح.

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

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