ندعوك للانضمام إلينا في يوم منتدى مطوّري "منصة خرائط Google" القادم في سان فرانسيسكو في ديسمبر. قدِّم طلبك الآن لحضور الفعالية.

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

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

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

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

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

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

إذا مرّرت 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 (ضمنًا). القيمة التلقائية هي 0.
fov: تحدّد هذه السمة مجال الرؤية الأفقي، ويتم التعبير عنها بالدرجات، مع حد أقصى للقيمة يبلغ 120. عند التعامل مع إطار عرض ثابت الحجم، كما هو الحال مع صورة "التجوّل الافتراضي" ذات الحجم المحدّد، يمثّل مجال الرؤية التكبير/التصغير، حيث تحدّد القيم الأصغر مستوى أعلى من التكبير/التصغير. القيمة التلقائية هي 90.

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

بعد الحصول على panoId، يمكنك طلب مربّع صورة في "صور التجوّل الافتراضي". طلبات المربّعات هي طلبات استرداد بيانات باستخدام GET عبر بروتوكول HTTPS. انظر المثال التالي.

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. بما أنّ الصور البانورامية أكبر في البُعد x، سيحتوي المربّع على مساحة فارغة في البُعد y:

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

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

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

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