سيتوفّر تصميم الخريطة الجديد قريبًا على "منصة خرائط 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`	لتوفير معلومات تفصيلية حول الصورة البانورامية المحددة. وتشمل التفاصيل العنوان ذي الصلة وروابط إلى صور بانورامية مجاورة.

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

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

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

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

طلبات البيانات الوصفية لميزة "التجوّل الافتراضي" تعرض معلومات عن الصور البانورامية. طلب البيانات الوصفية لميزة "التجوّل الافتراضي" هو طلب 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: المعرّف الفريد لهذه البانوراما ويجب ألا تعتمد على أرقام تعريف البانوراما صالحة لمدة أطول من جلسة مستخدم واحدة.
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: رابط تشعبي يمكن للمستخدمين استخدامه للإبلاغ عن المشاكل في مربّع ملف ‎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 في الردّ. لمزيد من المعلومات، اطّلِع على معلومات تحديد مصدر البيانات.