واجهة برمجة التطبيقات 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 لمشهد تجوّل افتراضي. تتيح لك توفير عنوان ودرجة صوت وأبعاد ومجال رؤية. الحد الأدنى للأبعاد هو 16×16 بكسل. الحد الأقصى للأبعاد هو 250x600 بكسل.
`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. تحتوي الصفيفة على قائمة بمعرفات البانوراما بالترتيب الذي طلبتها به. إذا لم تتمكن واجهة برمجة تطبيقات Tiles API من العثور على أي صور بانورامية للمواقع الجغرافية التي طلبتها، يتم عرض سلسلة فارغة في ذلك الموقع في الصفيف. على سبيل المثال، انظر رمز JSON التالي.

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

يمكنك استخدام "panoIds" لتنفيذ ما يلي:

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

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

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

في حال تمرير pano_id، ستعرض واجهة Map Tiles API البيانات الوصفية لتلك البانوراما.
ولكن إذا مررت lat وlng، ستعرض واجهة برمجة تطبيقات 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: رمز جغرافي منظم يحتوي على تفاصيل حول عنوان البانوراما. لمزيد من المعلومات، يمكنك الاطّلاع على طلبات واستجابات الترميز الجغرافي في مستندات Geocode 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 بمقدار tileHeight. نظرًا لأن الصور البانورامية أكبر في البعد "س"، سيحتوي المربّع على مساحة فارغة في البعد "ص":

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

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

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

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