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

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

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

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

يجب توفّر عارض لدمج مربّعات "التجوّل الافتراضي" معًا. على سبيل المثال، أداة عرض البانوراما المخصّصة في التجوّل الافتراضي.

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

1. احصل على رمز مميز للجلسة. تأكَّد من ضبط قيمة mapType على streetview.

2. استخدِم رمز الجلسة من أجل الحصول على معرّف الصورة البانورامية (panoId) لموقع جغرافي واحد أو أكثر.

3. استخدِم معرّفات البانوراما من استجابة البحث panoId للحصول على ما يلي:

   1. البيانات الوصفية في "التجوّل الافتراضي" يمكنك أيضًا الحصول على البيانات الوصفية الخاصة بخدمة Street View من خلال تمرير مجموعة من الإحداثيات ونصف القطر.

   2. الصور المصغّرة في "التجوّل الافتراضي"

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

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

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

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

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

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

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

تستردّ طلبات البيانات الوصفية في "التجوّل الافتراضي" معلومات عن الصور البانورامية. طلب البيانات الوصفية في Street View هو طلب استرداد بيانات باستخدام 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

المعرّف الفريد لهذه الصورة البانورامية. يجب عدم الاعتماد على أنّ معرّفات Panorama ستكون صالحة لمدة أطول من جلسة مستخدم واحدة.

"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

نص حقوق الطبع والنشر الذي يجب عرضه كإشارة إلى المصدر مع صورة Street View

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. عند التعامل مع إطار عرض ثابت الحجم، كما هو الحال مع صورة Street View ذات حجم محدّد، يمثّل مجال الرؤية مستوى التكبير، حيث تشير القيم الأصغر إلى مستوى تكبير أعلى. القيمة التلقائية هي 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 أوسع مجال للرؤية.

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

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

عند مستوى التكبير أو التصغير صفر، يتم تغيير حجم البانوراما بأكملها إلى مربّع بأبعاد tileWidth × tileHeight. بما أنّ الصور البانورامية أكبر في البُعد x، سيحتوي المربّع على مساحة فارغة في البُعد y:

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

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

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