顯示圖像和註解

歐洲經濟區 (EEA) 開發人員

Geocoding API 的 SearchDestinations 端點提供超區域背景資訊，包括導航點和入口。為提升使用者體驗，回應可包含 街景服務 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 欄位，其中包含下列欄位：

欄位 說明 靜態 API 參數
pano 特定全景 ID。 pano
widthPx 建議的圖片寬度。 size (寬度部分)
heightPx 建議的圖片高度。 size (高度部分)
headingDegree 攝影機的指南針方向 (0 到 360)。 heading
pitchDegree 攝影機的上下角度 (-90 至 90)。 pitch
fovDegree 水平視野 (0 到 120)。 fov

要求圖片

如要要求街景服務圖片，請使用 streetViewThumbnail 物件中的值，建構 Street View Static API 的網址。

範例網址

以下是建構的街景服務 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 函式示範如何從 Destinations 端點輸出內容建構 Static 街景服務 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 欄位中加入相應入口的圖片註解。這會提供多邊形的像素座標，標示縮圖中入口的輪廓。

這些註解適用於用戶端轉譯。您可以使用這些圖層在 Static API 傳回的圖片上繪製疊加層 (例如使用 SVG 或 <canvas>)。

註解座標系統

原點 (0,0) 是圖片的左上角。

  • xPx：與左側邊緣的水平距離。
  • yPx：與頂端的垂直距離。

為確保多邊形正確對齊，您必須使用 widthPx 和 heightPx 指定的 size，向 Static API 要求圖片。

程式碼範例：繪製註解 (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 提供意見。