واجهة برمجة التطبيقات Map Tiles API في مرحلة المعاينة حاليًا (ما قبل التوفّر للجمهور العام). قد يكون دعم المنتجات والميزات قبل التوفّر للجمهور العام محدودًا، وقد لا تتوافق التغييرات التي تطرأ على منتجات وميزات مرحلة ما قبل التوفّر للجمهور العام مع الإصدارات الأخرى المتاحة للجمهور العام. تخضع "عروض مرحلة ما قبل التوفّر للجمهور العام" للأحكام الخاصة بخدمة "منصة خرائط Google". لمزيد من المعلومات، يمكنك الاطّلاع على أوصاف مرحلة الإطلاق.

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

Switch to English

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

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

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

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

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

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

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

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

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

الطريقة	الوصف
`https://tile.googleapis.com/v1/streetview/tiles`	لعرض مربّعات التجوّل الافتراضي الفردية. يمكنك استرداد مربّعات التجوّل الافتراضي عند ستة مستويات للتكبير/التصغير: من 512 بكسل إلى 13312 بكسل.
`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. تحتوي المصفوفة على قائمة بمعرفات البانوراما بالترتيب الذي طلبتها به. إذا لم تتمكن API Tiles API من العثور على أي صور بانورامية للمواقع التي طلبتها، فسيتم عرض سلسلة فارغة في هذا الموقع في الصفيف. على سبيل المثال، انظر رمز JSON التالي.

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

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

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

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

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

إذا اجتزت pano_id، ستعرض واجهة برمجة تطبيقات Tiles API البيانات الوصفية لتلك البانوراما.
ولكن إذا مررت lat وlng، ستعرض واجهة برمجة تطبيقات مربعات الخرائط البيانات الوصفية لأقرب صورة بانورامية ضمن نصف قطر البحث المحدد.

تمرير مجموعة من الإحداثيات ونصف القطر

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: رمز جغرافي منظم يحتوي على تفاصيل حول عنوان الصورة البانورامية. لمزيد من المعلومات، راجِع طلبات واستجابات الترميز الجغرافي في مستندات واجهة برمجة التطبيقات لميزة الترميز الجغرافي.
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	45°
4	22.5°
5	11.25°

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

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

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

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

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

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

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

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