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

تحاول واجهة برمجة تطبيقات Map Tiles API العثور على أقرب بانوراما لكل موقع، ثم تعرض معرفات البانوراما الخاصة بها. يؤدي طلب 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: المعرّف الفريد لهذه البانوراما. ويجب ألا تعتمد على أرقام تعريف البانوراما صالحة لمدة أطول من جلسة مستخدم واحدة.
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 (ضمنًا). القيمة التلقائية s 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. نظرًا لأن الصور البانورامية تكون أكبر في البعد س، سيحتوي المربع على مساحة فارغة في البعد ص:

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

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

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

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