Geocoding API v4 methods have a default quota of 25 queries per second (QPS). For information on requesting a higher quota, see View and manage quotas and select Geocoding API as the service.

Display imagery and annotations

European Economic Area (EEA) developers

The Geocoding API's SearchDestinations endpoint provides hyperlocal context, including navigation points and entrances. To enhance user experience, the response can include parameters for the Street View Static API, allowing you to display relevant imagery for these locations.

Request imagery and annotations

To receive imagery and annotation information, you must include the following fields to the X-Goog-FieldMask header:

Example cURL request

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

Example JSON response

{
  "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
              }
            ]
          }
        }
      ]
    }
  ]
}

Featured fields

The Entrance and NavigationPoint objects in the response can contain a streetViewThumbnail field with the following fields:

Field	Description	Static API Parameter
`pano`	A specific panorama ID.	`pano`
`widthPx`	Suggested width for the image.	`size` (width part)
`heightPx`	Suggested height for the image.	`size` (height part)
`headingDegree`	Compass heading of the camera (0-360).	`heading`
`pitchDegree`	Up/down angle of the camera (-90 to 90).	`pitch`
`fovDegree`	Horizontal field of view (0-120).	`fov`

Request an image

To request a Street View image, use the values from the streetViewThumbnail object to construct a URL for the Street View Static API.

Example URL

The following is an example of a constructed Street View Static API URL:

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

Sample code: TypeScript

The following TypeScript function demonstrates how to construct the Static Street View API URL from the Destinations endpoint output.

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()}`;
}

Image annotations

If an Entrance or a NavigationPoint is returned, it can also include an image annotation of the corresponding entrance in the streetViewAnnotation or the entranceAnnotation field. This provides pixel coordinates for a polygon that outlines the entrance within the thumbnail image.

These annotations are intended for client-side rendering. You can use them to draw an overlay (for example, using SVG or a <canvas>) on top of the image returned by the Static API.

Annotation coordinate system

The origin (0,0) is the top-left corner of the image.

xPx: Horizontal distance from the left edge.
yPx: Vertical distance from the top edge.

To ensure the polygon aligns correctly, you must request the image from the Static API using the size specified by widthPx and heightPx.

Sample code: Drawing annotations (TypeScript and SVG)

This example demonstrates how to use TypeScript and SVG to overlay the entrance annotation polygon on the Street View image.

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>

You should see something similar to this:

Feedback

This is an experimental feature of the Geocoding API. We would appreciate feedback at geocoding-feedback-channel@google.com.