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

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

توفّر نقطة النهاية 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 مع الحقول التالية:

الحقل الوصف مَعلمة واجهة برمجة التطبيقات الثابتة
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=API_KEY&signature=YOUR_SIGNATURE

رمز نموذجي: TypeScript

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

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>) أعلى الصورة التي تعرضها واجهة برمجة التطبيقات الثابتة.

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

نقطة الأصل (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.