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