عرض الصور والتعليقات التوضيحية

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

تقدّم نقطة نهاية SearchDestinations في Geocoding API سياقًا على مستوى منطقة محلية صغيرة، بما في ذلك نقاط التنقّل والمداخل. لتحسين تجربة المستخدم، يمكن أن تتضمّن الاستجابة مَعلمات Street View Static API، ما يتيح لك عرض صور ذات صلة بهذه المواقع الجغرافية.

طلب الصور والتعليقات التوضيحية

لتلقّي معلومات حول الصور والتعليقات التوضيحية، يجب تضمين الحقول التالية في رأس X-Goog-FieldMask:

مثال على طلب cURL

curl -X POST -d '{
  "place": "places/ChIJkU89GL9ZwokRvVjWDQzhaNg"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: destinations.navigationPoints.streetViewThumbnail,destinations.navigationPoints.entranceAnnotation,destinations.entrances.streetViewThumbnail,destinations.entrances.streetViewAnnotation" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

مثال على استجابة JSON

{
  "destinations": [
    {
      "entrances": [
        {
          "location": {
            "latitude": 40.7406763,
            "longitude": -74.0020733
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJkU89GL9ZwokRvVjWDQzhaNg",
          "streetViewThumbnail": {
            "pano": "EUKaIR67fBVmpsHnXuIevA",
            "widthPx": 400,
            "heightPx": 600,
            "headingDegree": 331.06186,
            "fovDegree": 60
          },
          "streetViewAnnotation": {
            "coordinates": [
              {
                "xPx": 184.7,
                "yPx": 290.4
              },
              {
                "xPx": 213.3,
                "yPx": 289.4
              },
              {
                "xPx": 214.8,
                "yPx": 330.8
              },
              {
                "xPx": 186.0,
                "yPx": 332.5
              }
            ]
          }
        }
      ]
    }
  ]
}

يمكن أن يحتوي العنصران Entrance وNavigationPoint في الرد على الحقل streetViewThumbnail مع الحقول التالية:

الحقل الوصف Static API Parameter
pano معرّف بانوراما محدّد pano
widthPx تمثّل هذه السمة العرض المقترَح للصورة. size (جزء العرض)
heightPx الارتفاع المقترَح للصورة size (جزء الارتفاع)
headingDegree اتجاه البوصلة للكاميرا (من 0 إلى 360). heading
pitchDegree زاوية الكاميرا للأعلى/للأسفل (-90 إلى 90). pitch
fovDegree مجال الرؤية الأفقي (0-120) fov

طلب صورة

لطلب صورة "التجوّل الافتراضي"، استخدِم القيم من العنصر streetViewThumbnail لإنشاء عنوان URL خاص بـ Street View Static API.

مثال لعنوان URL

في ما يلي مثال على عنوان URL تم إنشاؤه لواجهة برمجة التطبيقات Street View Static API:

https://maps.googleapis.com/maps/api/streetview?size=400x600&pano=EUKaIR67fBVmpsHnXuIevA&heading=331.06186&fov=60&key=YOUR_API_KEY&signature=YOUR_SIGNATURE

نموذج الرمز البرمجي: TypeScript

توضّح دالة TypeScript التالية كيفية إنشاء عنوان URL الخاص بواجهة برمجة التطبيقات Static Street View من ناتج نقطة النهاية Destinations.

interface StreetViewThumbnail {
  pano: string;
  widthPx: number;
  heightPx: number;
  headingDegree: number;
  pitchDegree: number;
  fovDegree: number;
}

function getStreetViewUrl(thumbnail: StreetViewThumbnail, apiKey: string): string {
  const params = new URLSearchParams({
    size: `${thumbnail.widthPx}x${thumbnail.heightPx}`,
    pano: thumbnail.pano,
    heading: thumbnail.headingDegree.toString(),
    pitch: thumbnail.pitchDegree.toString(),
    fov: thumbnail.fovDegree.toString(),
    key: apiKey,
  });

  return `https://maps.googleapis.com/maps/api/streetview?${params.toString()}`;
}

التعليقات التوضيحية على الصور

إذا تم عرض Entrance أو NavigationPoint، يمكن أن يتضمّن أيضًا تعليقًا توضيحيًا للصورة الخاصة بالمدخل المعنيّ في الحقل streetViewAnnotation أو entranceAnnotation. تقدّم هذه السمة إحداثيات البكسل لمضلّع يحدّد المدخل ضمن الصورة المصغّرة.

هذه التعليقات التوضيحية مخصّصة للعرض من جهة العميل. يمكنك استخدامها لرسم طبقة عرض (على سبيل المثال، باستخدام SVG أو <canvas>) فوق الصورة التي تعرضها Static API.

نظام إحداثيات التعليقات التوضيحية

نقطة الأصل (0,0) هي الزاوية العلوية اليسرى من الصورة.

  • xPx: المسافة الأفقية من الحافة اليسرى
  • yPx: المسافة العمودية من الحافة العلوية

لضمان محاذاة المضلّع بشكل صحيح، يجب طلب الصورة من واجهة برمجة التطبيقات Static API باستخدام size المحدّد بواسطة widthPx وheightPx.

رمز نموذجي: رسم التعليقات التوضيحية (TypeScript وSVG)

يوضّح هذا المثال كيفية استخدام TypeScript وSVG لتراكب مضلّع التعليق التوضيحي الخاص بالمدخل على صورة &quot;التجوّل الافتراضي&quot;.

TypeScript

interface Coordinate {
  xPx: number;
  yPx: number;
}

interface StreetViewAnnotation {
  coordinates: Coordinate[];
}

function drawAnnotations(annotation: StreetViewAnnotation, width: number, height: number) {
  const svg = document.getElementById('annotation-overlay') as unknown as SVGSVGElement;
  const polygon = document.getElementById('entrance-polygon') as unknown as SVGPolygonElement;

  // Set SVG dimensions to match the image
  svg.setAttribute('width', width.toString());
  svg.setAttribute('height', height.toString());
  svg.setAttribute('viewBox', `0 0 ${width} ${height}`);

  // Construct points string for the polygon
  const points = annotation.coordinates
    .map(coord => `${coord.xPx},${coord.yPx}`)
    .join(' ');

  polygon.setAttribute('points', points);
}

// Example usage:
const annotation = {
  coordinates: [
    {xPx: 184.7, yPx: 290.4},
    {xPx: 213.3, yPx: 289.4},
    {xPx: 214.8, yPx: 330.8},
    {xPx: 186.0, yPx: 332.5}
  ]
};
drawAnnotations(annotation, 400, 600);

HTML

<div style="position: relative; display: inline-block;">
  <!-- The Street View image from the previous step -->
  <img id="street-view-image" src="STREET_VIEW_IMAGE" alt="Street View" style="display: block;">

  <!-- SVG overlay for annotations -->
  <svg id="annotation-overlay" style="position: absolute; top: 0; left: 0; pointer-events: none;">
    <polygon id="entrance-polygon" points="" style="fill:rgba(0, 255, 17, 0.3);stroke:rgba(0, 255, 17, 0.9);stroke-width:3" />
  </svg>
</div>

من المفترض أن يظهر لك ما يلي:

‫Google التجوّل الافتراضي في نيويورك

الملاحظات

هذه ميزة تجريبية في Geocoding API. يسرّنا تلقّي ملاحظاتك على geocoding-feedback-channel@google.com.