سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط 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. نص الطلب هو كائن 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 في العثور على أي صور بانورامية للمواقع التي طلبتها، فسيتم عرض سلسلة فارغة في هذا الموقع في الصفيف. على سبيل المثال، يمكنك الاطّلاع على رمز JSON البرمجي التالي.

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

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

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

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

تعمل طلبات البيانات الوصفية في "التجوّل الافتراضي" على استرداد معلومات عن الصور البانورامية. طلب البيانات الوصفية في StreetėmView هو طلب 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.

نتيجة طلب Tile ناجح

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

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

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

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

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