مقدمة
توفّر طلبات البيانات الوصفية لواجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" بيانات عن الصور البانورامية التي تم التقاطها باستخدام ميزة "التجوّل الافتراضي". باستخدام البيانات الوصفية، يمكنك معرفة ما إذا كانت صورة "التجوّل الافتراضي" متاحة في موقع جغرافي معيّن، بالإضافة إلى الحصول على وصول آلي إلى إحداثيات خطوط الطول والعرض ومعرّف البانوراما وتاريخ التقاط الصورة ومعلومات حقوق الطبع والنشر الخاصة بالصورة. ويتيح لك الوصول إلى هذه البيانات التعريفية تخصيص سلوك الخطأ في تطبيقك.
تتوفّر طلبات البيانات الوصفية الثابتة لواجهة برمجة التطبيقات في ميزة "التجوّل الافتراضي" بدون أي رسوم. لا يتم استهلاك أي حصة عند طلب البيانات الوصفية. لا يتم استهلاك حصة التخزين إلا عند تحميل صورة باستخدام واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي".
عند إرسال طلبات البيانات الوصفية لصور "التجوّل الافتراضي"، يمكن أن تصل درجة دقة الصور البانورامية إلى 50 مترًا.
الوصول إلى البيانات الوصفية للصور
طلب البيانات الوصفية للصورة في ميزة "التجوّل الافتراضي" هو عنوان URL ببروتوكول HTTP للنموذج التالي:
https://maps.googleapis.com/maps/api/streetview/metadata?parameters
وكما هو الحال بالنسبة إلى عناوين URL، يتم فصل جميع المعلمات باستخدام حرف العطف (&).
المَعلمات المطلوبة لطلبات البيانات الوصفية
تقبل طلبات البيانات الوصفية معلمات عناوين URL نفسها التي تطلبها طلبات صور واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي"، على الرغم من أنّ المعلمات التالية فقط هي المطلوبة:
يمكنك تنفيذ أحد الإجراءين التاليين:
location— يمكن أن تكون إما سلسلة نصية (مثلChagrin Falls, OH) أو زوجًا من إحداثيات خط العرض وخط الطول مفصولَين بفواصل (40.457375,-80.009353).
أو:
pano— رقم تعريف خاص للبانوراما. قد تغير الصور البانورامية المعرّفات بمرور الوقت، لذا لا تحتفظ بهذا المعرّف. بدلاً من ذلك، احفظ عنوان الموقع أو إحداثيات خطوط العرض والطول حتى تتمكن من تحديث معرّف البانوراما. لمعرفة التفاصيل، يُرجى الاطّلاع على إعادة تحميل معرّفات البانوراما المحذوفة.
بالإضافة إلى ذلك:
keyوsignature: مفتاح واجهة برمجة التطبيقات مطلوب لمصادقة الطلب. يكون التوقيع الرقمي مطلوبًا أيضًا في بعض الحالات ويُنصح باستخدامه دائمًا. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على مفتاح وتوقيع.
يظهر طلب البيانات الوصفية، مع المعلَمات المطلوبة فقط، على النحو التالي:
https://maps.googleapis.com/maps/api/streetview/metadata?location=&key=YOUR_API_KEY&signature=
أو مثل هذا:
https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=
إعادة تحميل معرّفات البانوراما المحذوفة
إذا حاولت استرداد معرّف بانوراما وحصلت على ZERO_RESULTS أو لم تظهر أي قيمة،
هذا يعني أنّه تم حذف رقم تعريف البانوراما ويجب إعادة تحميله.
احفظ عنوان الموقع أو إحداثيات خط العرض وخط الطول التي استخدمتها للحصول على معرّف بانوراما حتى تتمكن من التحديث عند الحاجة.
عند اكتشاف تغيير معرف البانوراما، استخدم عنوان الموقع الأصلي أو إحداثيات خط العرض وخط الطول للبحث مرة أخرى عن أقرب صور بانورامية لهذا الموقع والحصول على معرّف بانوراما جديد.
المَعلمات الاختيارية لطلبات البيانات الوصفية
يمكنك تضمين المَعلمات التالية في طلب البيانات الوصفية: size
وheading وfov وpitch. لاحظ أن هذه المعلمات لا تؤثر على
البيانات حول البانوراما، أو أي بانوراما يتم العثور عليها.
تسمح واجهة برمجة التطبيقات بتضمين المعلَمات نفسها مثل طلب الصور لتسهيل إنشاء طلب بيانات وصفية يتعلق بطلب صور معين، أما بالنسبة إلى طلبات البيانات الوصفية، تتجاهل واجهة برمجة التطبيقات المعلَمات الاختيارية وقيمها. للحصول على معلومات عن استخدام هذه المَعلمات، يمكنك الاطّلاع على دليل المطوِّر لواجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي".
تنسيق الردّ
ويتم عرض استجابات البيانات الوصفية بتنسيق JSON فقط.
أمثلة
المثال 1: تم العثور على صورة بانوراما
تطلب عناوين URL التالية بنجاح البيانات الوصفية والصورة نفسها للبانوراما.
طلب البيانات الوصفية والردّ عليها
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"copyright" : "© 2017 Google",
"date" : "2016-05",
"location" : {
"lat" : 48.85783227207914,
"lng" : 2.295226175151347
},
"pano_id" : "tu510ie_z4ptBZYo2BGEJg",
"status" : "OK"
}
طلب الصور والاستجابة لها، حيث من المتوقع عدم ظهور الصورة المفقودة
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=eiffel%20tower,%20paris,%20france&heading=-45&pitch=42&fov=110&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
المثال 2: لم يتم العثور على البانوراما
تطلب عناوين URL التالية البيانات الوصفية والصورة الخاصة ببانوراما لا يمكن العثور عليها في الموقع المحدد أو بالقرب منه.
طلب البيانات الوصفية والردّ
https://maps.googleapis.com/maps/api/streetview/metadata?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
{
"status" : "ZERO_RESULTS"
}
طلب الصور والردّ عليها
https://maps.googleapis.com/maps/api/streetview?size=600x300&location=78.648401,14.194336&fov=90&heading=235&pitch=10&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
رموز الحالة
يحتوي الحقل status ضمن عنصر استجابة البيانات الوصفية على حالة الطلب، وقد يحتوي على معلومات تصحيح الأخطاء لمساعدتك في تحديد سبب تعذُّر عمل طلب "التجوّل الافتراضي" وحلّها. قد يحتوي الحقل status على القيم التالية:
| الحالة | الوصف |
|---|---|
"OK" |
يشير إلى عدم حدوث أي أخطاء، وتم العثور على بانوراما وعرض البيانات الوصفية. |
"ZERO_RESULTS" |
يشير إلى عدم إمكانية العثور على بانوراما بالقرب من الموقع المقدم. يمكن أن تحدث هذه الاستجابة إذا قدمت معرف بانوراما غير موجود أو غير صالح. راجع [إعادة تحميل أرقام تعريف البانوراما المحذوفة](#refresh-pano). |
"NOT_FOUND" |
يشير إلى تعذّر العثور على سلسلة العنوان المقدّمة في المعلَمة location. قد تظهر هذه الرسالة في حال تقديم عنوان
غير متوفّر. |
"OVER_QUERY_LIMIT" |
يشير إلى أنّك تجاوزت الحصة اليومية أو الحصة في الثانية لواجهة برمجة التطبيقات هذه. |
"REQUEST_DENIED" |
يشير إلى رفض طلبك. قد تظهر هذه الرسالة في حال عدم تفويض طلبك، أو إذا لم يتم تفعيل واجهة برمجة التطبيقات الثابتة لميزة "التجوّل الافتراضي" في مشروع Google Cloud Console الذي يحتوي على مفتاح واجهة برمجة التطبيقات الخاص بك. |
"INVALID_REQUEST" |
يشير ذلك بشكل عام إلى أنّ معلَمات طلب البحث (العنوان أو إحداثيات خطوط الطول والعرض أو المكونات) غير متوفّرة. |
"UNKNOWN_ERROR" |
يشير إلى تعذُّر معالجة الطلب بسبب خطأ في الخادم. وغالبًا ما تكون هذه المشكلة مؤقتة. قد ينجح الطلب في حال إعادة المحاولة. |
مزيد من المعلومات
للحصول على مزيد من المعلومات حول استخدام واجهة برمجة تطبيقات التجوّل الافتراضي الثابتة، أو منتجات واجهة برمجة تطبيقات خرائط Google الأخرى، تأكد من الاطلاع على صفحة الدعم في واجهة برمجة تطبيقات الخرائط.