سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط 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 لمشهد في "التجوّل الافتراضي". يتيح لك تقديم عنوان ودرجة ميل وقياسات ومجال رؤية. الحد الأدنى للأبعاد هو 16 × 16 بكسل. الحد الأقصى للأبعاد هو 250×600 بكسل.
`https://tile.googleapis.com/v1/streetview/metadata`	يوفّر معلومات مفصّلة عن البانوراما المحدّدة. وتشمل التفاصيل العنوان ذي الصلة وروابط إلى صور بانورامية مجاورة.

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

يمكنك العثور على معرّف بانوراما لموقع جغرافي واحد أو أكثر من خلال إرسال إحداثياته (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 لأوسع مجال رؤية.

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

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

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

نتيجة طلب مربّع شاشة ناجح

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

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

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

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

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