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

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

توفر نقطة النهاية 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
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 تم إنشاؤه لواجهة برمجة تطبيقات التجوّل الافتراضي الثابتة:

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

رمز نموذجي: TypeScript

توضّح دالّة TypeScript التالية كيفية إنشاء عنوان URL لـ Static Street View API من ناتج نقطة نهاية 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 لتراكب مضلّع التعليق التوضيحي للمدخل على صورة "التجوّل الافتراضي".

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.