سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط Google". يتضمن هذا التحديث على تصميم الخريطة لوحة ألوان تلقائية جديدة وتحسينات على تجارب الخرائط وسهولة الاستخدام. سيتم تعديل جميع أنماط الخرائط تلقائيًا في آذار (مارس) 2025. للمزيد من المعلومات عن مدى التوفّر وكيفية تفعيل الميزة في وقت سابق، يُرجى الاطّلاع على نمط الخريطة الجديد في "منصة خرائط Google".

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

احصل على الرمز المميز للجلسة. يجب ضبط قيمة mapType على streetview
استخدِم الرمز المميّز للجلسة للحصول على معرّف البانوراما (panoId) لموقع جغرافي واحد أو أكثر.
استخدِم معرّفات البانوراما من استجابة البحث panoId للحصول على:
1. البيانات الوصفية لميزة "التجوّل الافتراضي": يمكنك أيضًا الحصول على بيانات "التجوّل الافتراضي" الوصفية من خلال تمرير مجموعة من الإحداثيات ونطاق جغرافي.
2. الصور المصغّرة لميزة "التجوّل الافتراضي":
3. مربّعات "التجوّل الافتراضي":

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

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

الطريقة	الوصف
`https://tile.googleapis.com/v1/streetview/tiles`	لعرض مربّعات "التجوّل الافتراضي" الفردية يمكنك استرداد مربعات "التجوّل الافتراضي" بستة مستويات للتكبير: من 512 بكسل إلى 13,312 بكسل.
`https://tile.googleapis.com/v1/streetview/panoIds`	يمكنك البحث بشكل مجمّع عن ما يصل إلى 100 موقع جغرافي. لعرض معرفات بانوراما لجميع المواقع التي تحتوي على صور.
`https://tile.googleapis.com/v1/streetview/thumbnail`	يتم عرض صورة مصغّرة بتنسيق JPEG لمشهد التجوّل الافتراضي. تتيح لك تقديم العنوان ودرجة الصوت والأبعاد ومجال الرؤية. الحد الأدنى للأبعاد هو 16x16 بكسل. الحد الأقصى للأبعاد هو 250×600 بكسل.
`https://tile.googleapis.com/v1/streetview/metadata`	يتم توفير معلومات تفصيلية حول الصورة البانورامية المحدّدة. تشتمل التفاصيل على العنوان ذي الصلة وروابط إلى الصور البانورامية المجاورة.

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

يمكنك العثور على المعرّف البانورامي لموقع جغرافي واحد أو أكثر من خلال تمرير إحداثياته (lat، lng) إلى طريقة panoIds. نص الطلب هو كائن 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

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

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

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

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

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

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

في حال اجتياز pano_id، ستعرض واجهة Map Tiles API البيانات الوصفية لتلك البانوراما.
ولكن إذا مررت 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 ID صالحة لأكثر من جلسة مستخدم واحدة.
lat، lng: إحداثيات (خط العرض وخط الطول) للبانوراما. ويمكن أن تختلف هذه القيم عن الإحداثيات التي مررت بها في الطلب لأن الموقع الجغرافي ينظف إلى أقرب صورة بانورامية.
imageHeight، imageWidth: أبعاد صورة البانوراما المدمَجة
tileHeight، tileWidth: أبعاد مربّع بانوراما واحد
heading: اتجاه البوصلة من ناحية الدرجات، يتم قياسه بالدرجات في اتجاه عقارب الساعة من الشمال. يتم عرض العناوين ضمن النطاق [0,360]، حيث يشير الرقم 0 إلى الشمال المستحق.
tilt: يتم قياس إمالة البانوراما بالدرجات من القطب الجنوبي للصورة البانورامية إلى الأفق. تقع القيم المعروضة ضمن النطاق [0، 180]. وتشير القيمة 90 درجة إلى أنه تمت محاذاة الأفق بالفعل عند خط الاستواء.
roll: التدوير في اتجاه عقارب الساعة حول خط الرؤية الذي تم تطبيقه على الصورة البانورامية لتسوية الأفق. تقع القيم المعروضة ضمن النطاق [0، 360].
imageryType: تشير هذه العلامة إلى نوع الصورة. القيمتان الصالحتان هما indoor وoutdoor.
date: تاريخ التقاط الصورة. لا تحتوي بعض الصور على بيانات تاريخ. ولكن عندما يكون هذا الحقل متاحًا، يحتوي على تركيبة من العام (YYYY) والشهر (MM). على سبيل المثال: 2023-05 أو 2024.
copyright: نص حقوق الطبع والنشر الذي يجب عرضه كمرجع مع صورة "التجوّل الافتراضي"
reportProblemLink: رابط تشعّبي يمكن للمستخدمين استخدامه للإبلاغ عن المشاكل المتعلّقة بمربّع "التجوّل الافتراضي" هذا. يجب عرض هذا الرابط التشعّبي في أسفل يسار الصورة، ويجب أن يتضمّن نص الرابط عبارة مثل "الإبلاغ عن مشكلة في هذه الصورة".
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 أوسع مجال رؤية.

مستوى التكبير أو التصغير	حقل العرض التقريبي
0	360 درجة
1	180 درجة
2	90 درجة
3	7 درجات
4	22.5 درجة
5	11.25°

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

يعرض طلب مربّع "التجوّل الافتراضي" الناجح صورة بالتنسيق والحجم الذي حدّدته في ردّ createSession.

نتيجة طلب "تقسيم الشاشة" بنجاح

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

مستوى التكبير/التصغير صفر

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

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

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