Mostrar imagens e anotações

Desenvolvedores do Espaço Econômico Europeu (EEE)

O endpoint SearchDestinations da API Geocoding fornece contexto hiperlocal, incluindo pontos de navegação e entradas. Para melhorar a experiência do usuário, a resposta pode incluir parâmetros da API Street View Static, permitindo que você mostre imagens relevantes desses locais.

Solicitar imagens e anotações

Para receber imagens e informações de anotação, inclua os seguintes campos no cabeçalho X-Goog-FieldMask:

Exemplo de solicitação 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

Exemplo de resposta 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
              }
            ]
          }
        }
      ]
    }
  ]
}

Os objetos Entrance e NavigationPoint na resposta podem conter um campo streetViewThumbnail com os seguintes campos:

Campo Descrição Parâmetro da API estática
pano Um ID de panorama específico. pano
widthPx Largura sugerida para a imagem. size (parte da largura)
heightPx Altura sugerida para a imagem. size (parte da altura)
headingDegree Direção da bússola da câmera (0 a 360). heading
pitchDegree Ângulo vertical da câmera (-90 a 90). pitch
fovDegree Campo de visão horizontal (0 a 120). fov

Pedir uma imagem

Para solicitar uma imagem do Street View, use os valores do objeto streetViewThumbnail para criar um URL para a API Street View Static.

URL de exemplo

Este é um exemplo de URL construído da API Street View Static:

https://maps.googleapis.com/maps/api/streetview?size=400x600&pano=EUKaIR67fBVmpsHnXuIevA&heading=331.06186&fov=60&key=API_KEY&signature=YOUR_SIGNATURE

Exemplo de código: TypeScript

A função TypeScript a seguir demonstra como construir o URL da API Static Street View com base na saída do endpoint 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()}`;
}

Anotações de imagens

Se um Entrance ou um NavigationPoint for retornado, ele também poderá incluir uma anotação de imagem da entrada correspondente no campo streetViewAnnotation ou entranceAnnotation. Isso fornece coordenadas de pixel para um polígono que descreve a entrada na imagem em miniatura.

Essas anotações são destinadas à renderização do lado do cliente. É possível usar esses elementos para desenhar uma sobreposição (por exemplo, usando SVG ou um <canvas>) na parte de cima da imagem retornada pela API Static.

Sistema de coordenadas de anotação

A origem (0,0) é o canto superior esquerdo da imagem.

  • xPx: distância horizontal da borda esquerda.
  • yPx: distância vertical da borda superior.

Para garantir que o polígono esteja alinhado corretamente, é necessário solicitar a imagem da API Static usando o size especificado por widthPx e heightPx.

Exemplo de código: anotações de desenho (TypeScript e SVG)

Este exemplo demonstra como usar TypeScript e SVG para sobrepor o polígono de anotação da entrada na imagem do 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>

Você verá algo como:

Street View do Google em Nova York

Feedback

Este é um recurso experimental da API Geocoding. Agradecemos seu feedback em geocoding-feedback-channel@google.com.