بلاط التجوّل الافتراضي

تشبه مربّعات "التجوّل الافتراضي" المربّعات ثنائية الأبعاد باستثناء أنّها تحتوي على صور بانورامية تم التقاطها على مستوى الشارع. باستخدام "التجوّل الافتراضي"، يمكنك استكشاف المَعالم الشهيرة في العالم ومشاهدة عجائب الدنيا الطبيعية والتجوّل داخل أماكن مختلفة مثل المتاحف أو الساحات أو المطاعم أو الأنشطة التجارية الصغيرة. تتيح لك نقطة نهاية واجهة برمجة التطبيقات هذه الوصول إلى ما يلي:

• مربّعات "التجوّل الافتراضي" في "خرائط Google"
• البيانات الوصفية في "التجوّل الافتراضي"
• الصور المصغّرة لميزة "التجوّل الافتراضي"

يمكنك دمج مربّعات الصور التي تم التقاطها من مستوى الشارع لإنشاء تأثير بانورامي مماثل للواقع. ويمكنك طلب ما يصل إلى 100 معرّف بانورامي لمجموعة من المواقع الجغرافية (مثل مسار)، والحصول على بيانات وصفية أكثر تفصيلاً عن موقع الكاميرا.

على المشاهد دمج مربّعات "التجوّل الافتراضي" معًا. على سبيل المثال، أداة عرض البانوراما المخصّصة في التجوّل الافتراضي

بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكنك الوصول إلى صور "التجوّل الافتراضي" من خلال تنفيذ الخطوات التالية.

1. الحصول على رمز مميز للجلسة احرص على ضبط قيمة mapType على streetview.

2. استخدِم رمز الجلسة لالحصول على معرّف المنظر البانورامي (panoId) لموقع جغرافي واحد أو أكثر.

3. استخدِم معرّفات الصور البانورامية من استجابة البحث عن panoId للحصول على ما يلي:

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

   2. الصور المصغّرة لميزة "التجوّل الافتراضي"

   3. مربّعات "التجوّل الافتراضي"

طرق "التجوّل الافتراضي"

يمكنك الوصول إلى صور "التجوّل الافتراضي" والبيانات الوصفية من خلال الاتصال باستخدام إحدى الخطوات التالية:

البحث عن معرّفات بانوراما في "التجوّل الافتراضي"

يمكنك العثور على معرّف بانوراما لموقع جغرافي واحد أو أكثر من خلال إرسال إحداثياته (lat وlng) إلى طريقة panoIds. locationsbodyradius الطلب هو عنصر JSON يحتوي على مصفوفة locations وradius اختياريًا، كما هو موضّح في مثال رمز JSON التالي.

curl -X POST -d '{
  "locations": [
    {"lat": -33.883837, "lng": 151.209307},
    {"lat": -33.883700, "lng": 151.210307},
    {"lat": 0, "lng": 0}
  ],
  "radius": 50
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

يجب أن تحتوي مصفوفة locations على مجموعة واحدة على الأقل من قيم التنسيقات، ولكن يمكنك تضمين المزيد، حتى 100 كحد أقصى.

radius

تحدّد قيمة radius (المقاسة بالمتر) نطاق الدائرة حول الموقع الجغرافي المحدّد للبحث عن صور بانورامية. القيمة التلقائية هي 50 مترًا.

استجابة PanoId

تحاول واجهة برمجة التطبيقات Map Tiles API العثور على الصورة البانورامية الأقرب إلى كل موقع جغرافي، ثم تعرِض معرّفات الصور البانورامية. يعرض طلب panoIds الناجح ملفًا شخصيًا بتنسيق JSON يحتوي على مصفوفة panoIds. تحتوي المصفوفة على قائمة بأرقام تعريف المناظر البانورامية بالترتيب الذي طلبتها به. إذا تعذّر على واجهة برمجة التطبيقات Map Tiles API العثور على أي صور بانورامية للمواقع الجغرافية التي طلبتها، يتم عرض سلسلة فارغة في هذا الموضع في الصفيف. على سبيل المثال، يمكنك الاطّلاع على رمز JSON البرمجي التالي.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

يمكنك استخدام panoIds لإجراء ما يلي:

• طلب البيانات الوصفية لميزة "التجوّل الافتراضي"
• طلب صور مصغّرة لميزة "التجوّل الافتراضي"
• طلب مربّعات في "التجوّل الافتراضي"

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

تعمل طلبات البيانات الوصفية في "التجوّل الافتراضي" على استرداد معلومات عن الصور البانورامية. طلب البيانات الوصفية في Streetmekle هو طلب HTTPS GET. يمكنك استرداد معلومات عن الصور البانورامية بإحدى الطريقتين التاليتَين:

• في حال تمّ إدخال pano_id، ستُعرِض Map Tiles API البيانات الوصفية لتلك panorama.

• ولكن إذا أرسلت lat وlng، ستُرجع Map Tiles API البيانات الوصفية لأقرب صورة بانورامية ضمن نطاق البحث المحدّد.

نقْل مجموعة من الإحداثيات ونصف قطر

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

بما أنّ أرقام تعريف البانوراما مؤقتة، ننصحك بإرسال مجموعة من الإحداثيات وقيمة radius في طلب البيانات الوصفية الأوّلي لميزة "التجوّل الافتراضي". على سبيل المثال، راجِع المقتطف التالي من الرمز.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

تمرير مَعلمة panoId لصورة "التجوّل الافتراضي"

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

استجابة البيانات الوصفية

رمز JSON التالي هو مثال على استجابة البيانات الوصفية المعتادة.

{
 "panoId": "rZ9KeTyhA11i0VppYNzsSg",
 "lat": 37.420864219339165,
 "lng": -122.08446528377291,
 "imageHeight": 6656,
 "imageWidth": 13312,
 "tileHeight": 512,
 "tileWidth": 512,
 "heading": 94.35,
 "tilt": 88.39652,
 "roll": 1.7181772,
 "imageryType": "outdoor",
 "date": "2023-01",
 "copyright": "© 2023 Google",
 "reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
 "addressComponents": [
  {
   "longName": "United States",
   "shortName": "United States",
   "types": [
    "country"
   ]
  },
  {
   "longName": "Mountain View, California",
   "shortName": "Mountain View, California",
   "types": [
    "locality"
   ]
  },
  {
   "longName": "Charleston Rd",
   "shortName": "Charleston Rd",
   "types": [
    "route"
   ]
  },
  {
   "longName": "1635",
   "shortName": "1635",
   "types": [
    "street_number"
   ]
  }
 ],
 "links": [
  {
   "panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
   "heading": 274.47998046875,
   "text": "Charleston Rd"
  },
  {
   "panoId": "1cODYwFRw1aZ45IignDIMw",
   "heading": 94.47999572753906,
   "text": "Charleston Rd"
  }
 ]
}

تحتوي القائمة التالية على تعريفات للحقول في نص الاستجابة.

panoId

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

lat، lng

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

imageHeight، imageWidth

أبعاد صورة البانوراما المُدمَجة

tileHeight، tileWidth

أبعاد مربّع بانورامي واحد:

heading

اتجاه البوصلة، يتم قياسه بالدرجات في اتجاه عقارب الساعة من الشمال. يتم عرض الاتجاهات ضمن النطاق [0,360]، حيث يمثّل الصفر الاتجاه الشمالي.

tilt

ميل الصورة البانورامية، ويتم قياسه بالدرجات من القطب الجنوبي لل الصورة البانورامية إلى الأفق. القيم المعروضة ضمن النطاق [0, 180] تشير القيمة 90 درجة إلى أنّ الأفق قد تمّت محاذاته على خط الاستواء في المشهد البانورامي.

roll

التدوير باتجاه عقارب الساعة حول خط الرؤية الذي تم تطبيقه على المشهد المتكامل لتعديل الأفق تندرج القيم المعروضة ضمن النطاق [0, 360].

imageryType

يشير إلى نوع الصورة. القيم الصالحة هي indoor وoutdoor.

date

تاريخ التقاط الصورة لا تحتوي بعض الصور على بيانات التاريخ. ولكن عندما يكون متاحًا، يحتوي هذا الحقل على تركيبة من السنة (YYYY) والشهر (MM). على سبيل المثال: ‎2023-05 أو 2024.

copyright

نص حقوق الطبع والنشر الذي يجب عرضه كنسبة مع صورة "عرض الشارع"

reportProblemLink

رابط تشعبي يمكن للمستخدمين استخدامه للإبلاغ عن المشاكل في مربّع ملف ‎street view يجب عرض هذا الرابط التشعّبي في الركن السفلي الأيسر من الصورة، ويجب أن يتضمّن نص الرابط عبارة مثل "الإبلاغ عن مشكلة في هذه الصورة".

addressComponent

رمز جغرافي منظَّم يحتوي على تفاصيل عن عنوان البانوراما لمزيد من المعلومات، اطّلِع على طلبات الترميز الجغرافي والردود في مستندات Geocoding API.

links

قائمة بأرقام تعريف المناظر البانورامية التي ترتبط بهذه المناظر يحتوي أيضًا على العنوان الذي يظهر فيه الرابط. على سبيل المثال، إذا كان الاتجاه 180 درجة، تكون البانوراما الملتصقة في الجنوب من البانوراما الحالية. يُرجى العلم أنّه بسبب الطبيعة المؤقتة لأرقام تعريف البانوراما، يجب عدم الاعتماد عليها لأكثر من جلسة مستخدم واحدة.

الصور المصغّرة لميزة "التجوّل الافتراضي"

يمكنك طلب صور "التجوّل الافتراضي" بتنسيق thumbnail. الصور المصغّرة هي صور غير مصغّرة بحجم وعنوان ودرجة ميل ومستوى رؤية يحدّدها المستخدم. تكون درجة دقة الصور المصغّرة أقل من درجة دقة المربّعات، وتكون حجم ملفها أصغر. يمكنك طلب صورة مصغّرة من خلال إرسال طلب GET إلى نقطة النهاية thumbnail ، كما هو موضّح في النموذج الأولي للرمز البرمجي التالي.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId&height=FROM_16_TO_250&width=FROM_16_TO_600&pitch=FROM-90_TO_90&yaw=FROM-360_TO_360&fov=FROM_30_TO_120"

راجِع المثال التالي على الرمز البرمجي الذي ينزِّل صورة مصغّرة لصور "التجوّل الافتراضي" التي تم التقاطها في وايتشل، كندا.

curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=Zzl28rqGJgaL2IdkUleP8A&height=200&width=200&pitch=0&yaw=250&fov=80" --output /tmp/example_thumbnail.png

المعلمات المطلوبة

panoId

المعرّف الفريد للصورة المصغّرة التي تريدها يمكنك الحصول على قيم معرّفات المناظر البانورامية من نقطة نهاية panoIds أو من نقطة نهاية metadata، وكلتاهما تقبل الإحداثيات الجغرافية، وتُعرِض panoId المناسب.

session

رمز مميز صالح للجلسة:

key

مفتاح واجهة برمجة التطبيقات:

المعلمات الاختيارية

height

تحدد هذه السمة ارتفاع الصورة المصغّرة بالبكسل، ويتراوح من 16 بكسل إلى 250 بكسل. إذا لم تحدّد ارتفاعًا، سيتم ضبط الارتفاع تلقائيًا على الحد الأقصى المسموح به وهو 250 بكسل. إذا حدّدت قيمة خارج النطاق، يتم تعديل الصورة المصغّرة لتصبح أقرب قيمة صالحة.

width

تُحدِّد هذه السمة عرض الصورة المصغّرة بالبكسل، ويتراوح من 16 بكسل إلى 600 بكسل. إذا لم تحدّد عرضًا، سيتم ضبط العرض تلقائيًا على الحد الأقصى للقيمة المسموح بها وهو 600 بكسل. إذا حدّدت قيمة خارج النطاق، تتم تثبيت الصورة المصغّرة على أقرب قيمة صالحة.

pitch

تُستخدَم لتحديد زاوية الكاميرا على المحور الرأسي. القيم الصالحة هي في النطاق -90 إلى 90 (شاملة). القيمة التلقائية هي 0.

yaw

تُحدِّد اتجاه الكاميرا على طول المحور الأفقي. القيم الصالحة تتراوح بين -360 و360 (شاملة). القيمة التلقائية هي 0.

fov

تُحدِّد مجال الرؤية الأفقي، معبرًا عنه بالدرجات، والحد الأقصى لقيمة هو 120. عند التعامل مع مساحة عرض ذات حجم ثابت، كما هو الحال مع صورة "التجوّل الافتراضي" بحجم محدّد، يمثّل مجال العرض التكبير/التصغير، حيث تحدّد القيم الأصغر مستوى أعلى من التكبير/التصغير. القيمة التلقائية هي 90.

مربّعات صور "التجوّل الافتراضي"

بعد الحصول على panoId، يمكنك طلب مربّع صورة في "التجوّل الافتراضي". طلبات ملف التمرير هي طلبات HTTPS GET. راجِع المثال التالي.

curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&panoId=panoId"

في مثال الرمز البرمجي هذا، يمثّل z مستوى التكبير، ويمثّلx وy إحداثيات المربّع للمربّع الذي تريده في "التجوّل الافتراضي". يجب أن تكون مستويات التكبير/التصغير في الصور البانورامية في "التجوّل الافتراضي" في النطاق [0,5] مع تمثيل القيمة 0 لأوسع مجال رؤية.

الردود على مربّعات "التجوّل الافتراضي"

يؤدي طلب مربّع "التجوّل الافتراضي" الناجح إلى عرض صورة بالشكل والحجم اللذين حدّدتهما في ردّ createSession.

عند مستوى التكبير صفر، يتم تغيير حجم المشهد البانورامي بالكامل إلى مربّع أبعاده tileWidth x ‏tileHeight. بما أنّ الصور البانورامية أكبر في السمة x، سيحتوي المربّع على مساحة فارغة في السمة y:

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

معلومات حقوق الطبع والنشر

يجب عرض معلومات حقوق الطبع والنشر مع كل صورة بانورامية في "التجوّل الافتراضي". يمكن أن تختلف السلسلة المعروضة بين الصور البانورامية. للحصول على معلومات حقوق الطبع والنشر، يجب طلب البيانات الوصفية لميزة "التجوّل الافتراضي"، ثم يمكنك الرجوع إلى الحقل copyright في الردّ. لمزيد من المعلومات، يُرجى الاطّلاع على عمليات تحديد المصدر بالاستناد إلى البيانات.