البيانات الوصفية لصور "التجوّل الافتراضي"

مقدمة

تقدّم طلبات البيانات الوصفية في واجهة برمجة التطبيقات Street View Static API بيانات عن الصور البانورامية في "التجوّل الافتراضي". باستخدام البيانات الوصفية، يمكنك معرفة ما إذا كانت صورة "التجوّل الافتراضي" متوفرة في موقع جغرافي معيّن، بالإضافة إلى الحصول على إذن بالوصول الآلي إلى إحداثيات خطي الطول والعرض ورقم تعريف البانوراما وتاريخ التقاط الصورة ومعلومات حقوق الطبع والنشر للصورة. يتيح لك الوصول إلى هذه ال metadata تخصيص سلوك الأخطاء في تطبيقك.

تتوفّر طلبات البيانات الوصفية من واجهة برمجة التطبيقات Street View Static API بدون أي رسوم. لا يتم استخدام أي حصة عند طلب البيانات الوصفية. لا يتم استخدام الحصة إلا عند تحميل صورة باستخدام Street View Static API.

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

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

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

المَعلمات الاختيارية لطلبات البيانات الوصفية

يمكنك تضمين المَعلمات التالية في طلب البيانات الوصفية: size وheading وfov وpitch. تجدر الإشارة إلى أنّ هذه المَعلمات لا تؤثّر في البيانات المتعلّقة بالبانوراما أو البانوراما التي يتم العثور عليها. تسمح واجهة برمجة التطبيقات بتضمين المَعلمات نفسها المضمّنة في طلب الصور لتسهيل إنشاء طلب بيانات وصفية مرتبط بطلب محدد لصور، ولكن بالنسبة إلى طلبات البيانات الوصفية، تتجاهل واجهة برمجة التطبيقات المَعلمات الاختيارية وقيمتها. للحصول على معلومات عن استخدام هذه المَعلمات، يُرجى الاطّلاع على دليل المطوّر لواجهة برمجة التطبيقات Street View Static API.

تنسيق الردّ

يتم عرض الردود على البيانات الوصفية بتنسيق 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 Maps API الأخرى، يُرجى الاطّلاع على صفحة دعم واجهة برمجة التطبيقات "خرائط Google".