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

مقدمة

تقدّم طلبات البيانات الوصفية في 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 ضمن عنصر استجابة البيانات الوصفية على حالة الطلب، وقد يتضمّن معلومات تصحيح الأخطاء لمساعدتك في تحديد سبب عدم عمل طلب Street View. قد يحتوي الحقل status على القيم التالية:

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

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