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

مقدمة

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

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

عند تقديم طلبات البيانات الوصفية لصور "التجوّل الافتراضي"، تكون صور البانوراما دقيقة في نطاق 50 مترًا.

الوصول إلى البيانات الوصفية للصور

طلب البيانات الوصفية لصورة "التجوّل الافتراضي" هو عنوان URL يستخدم HTTP بالشكل التالي:

https://maps.googleapis.com/maps/api/streetview/metadata?parameters

كما هو معتاد في عناوين URL، يتم الفصل بين جميع المَعلمات باستخدام رمز العطف اللاتيني (&).

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

تقبل طلبات البيانات الوصفية مَعلمات عناوين URL نفسها التي تقبلها طلبات الصور في Street View Static API، ولكن لا تكون المَعلمات التالية مطلوبة إلا في الحالات التالية:

يمكنك إجراء ذلك بإحدى طريقتين:

• ‫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=<YOUR_SIGNATURE>

أو على النحو التالي:

https://maps.googleapis.com/maps/api/streetview/metadata?pano=&key=YOUR_API_KEY&signature=<YOUR_SIGNATURE>

إعادة تحميل معرّفات الصور البانورامية المحذوفة

إذا حاولت استرداد معرّف بانوراما وحصلت على ZERO_RESULTS أو لم تحصل على أي قيمة، يعني ذلك أنّه تم حذف معرّف البانوراما ويجب إعادة تحميله.

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 على القيم التالية:

مزيد من المعلومات

لمزيد من المعلومات حول استخدام Street View Static API أو منتجات Google Maps API الأخرى، يُرجى الاطّلاع على صفحة الدعم الخاصة بواجهة Maps API.