הצגת תמונות והערות

מפתחים באזור הכלכלי האירופי (EEA)

נקודת הקצה (endpoint) של Geocoding API‏, SearchDestinations, מספקת הקשר היפר-לוקאלי, כולל נקודות ניווט וכניסות. כדי לשפר את חוויית המשתמש, התגובה יכולה לכלול פרמטרים של 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

בקשת תמונה

כדי לבקש תמונה של Street View, משתמשים בערכים מאובייקט 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 מהפלט של נקודת הקצה 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 כדי להוסיף את מצולע ההערה של הכניסה לתמונת Street View.

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 NYC Street View

משוב

זוהי תכונה ניסיונית של Geocoding API. נשמח לקבל משוב בכתובת geocoding-feedback-channel@google.com.