طلب صورة "التجوّل الافتراضي" هو عنوان 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 أو لم تظهر أي قيمة، يعني ذلك أنّه تم حذف رقم تعريف البانوراما ويجب إعادة تحميله.
احفظ عنوان الموقع الجغرافي أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على معرّف بانوراما حتى تتمكّن من إعادة تحميلها عند الحاجة.
عندما تلاحظ أنّ رقم تعريف البانوراما قد تغيّر، استخدِم عنوان الموقع الجغرافي الأصلي أو إحداثيات خط العرض وخط الطول للبحث مرة أخرى عن أقرب صور بانورامية إلى هذا الموقع الجغرافي والحصول على رقم تعريف بانوراما جديد.
المعلمات الاختيارية
-
signature(يُنصح به) هو توقيع رقمي يُستخدم للتأكّد من أنّ أي موقع إلكتروني ينشئ طلبات باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك لديه الإذن بإجراء ذلك، وقد يتعذّر تنفيذ الطلبات التي لا تتضمّن توقيعًا رقميًا. لمزيد من المعلومات، اطّلِع على الحصول على مفتاح وتوقيع.ملاحظة: بالنسبة إلى عملاء "خطة Premium" السابقة في منصة خرائط Google، يجب تقديم توقيع رقمي. يمكنك الاطّلاع على مزيد من المعلومات حول مَعلمات المصادقة لعملاء خطة 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 بدلاً من الصورة الرمادية العامة، وذلك في حال عدم توفّر صورة للموقع الجغرافي المحدّد. - يمكنك طلب البيانات الوصفية لصور "التجوّل الافتراضي" لتحديد ما إذا كانت هناك صور متاحة للموقع الجغرافي المحدّد قبل إرسال طلب.