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

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

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

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

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

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

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

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

  1. احصل على الرمز المميز للجلسة. احرص على ضبط قيمة mapType على streetview.

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

  3. استخدِم معرّفات البانوراما من استجابة البحث عن 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.

نتيجة طلب ناجح لـ Tile

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

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

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

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