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:
-
destinations.navigationPoints.streetViewThumbnail -
destinations.navigationPoints.entranceAnnotation -
destinations.entrances.streetViewThumbnail -
destinations.entrances.streetViewAnnotation
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 cornerof the image.
-
xPx: Horizontal distance from the left edge. -
yPx: Vertical distance from the top edge.
To ensure the polygon aligns correctly, you mustrequest 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 .
