显示图像和注释

欧洲经济区 (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 的网址。

示例网址

以下是构建的街景静态 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 提供反馈。