לשיטות של Geocoding API v4 מוגדרת כברירת מחדל מכסה של 25 שאילתות לשנייה (QPS). מידע על בקשה להגדלת המכסה זמין במאמר איך רואים ומנהלים את המכסות. צריך לבחור באפשרות Geocoding API כשירות.

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

מפתחים באזור הכלכלי האירופי (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=YOUR_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>

הפלט אמור להיראות כך:

משוב

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