Introduction
The Maps Embed API lets you place an interactive map, or Street View
panorama on your site with a simple HTTP request. It can be easily embedded in
your web page or blog by setting the Maps Embed API URL as the
src
attribute of an iframe:
<iframe width="600" height="450" frameborder="0" style="border:0" src="https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY &q=Space+Needle,Seattle+WA" allowfullscreen> </iframe>
A map built for you
Every visitor to your site sees a Google Map tailored just for them. If they're signed in with their Google account, their saved places, home and work locations, and more are built right into the map they see. This also means that interactions with the map, such as starring a location, are saved for easy viewing in Google Maps for desktop or mobile.
These user-specific details aren't visible to other users. Each visitor sees a map that's built just for them.
Easy embedding
Maps Embed API maps are easy to add to your webpage—just set
the URL you build as the value of an iframe's src
attribute. Control the size
of the map with the iframe's height
and width
attributes. No JavaScript
required.
Advertisements on the map
The Maps Embed API may include on-map advertising. The ad format and the set of ads shown in any given map may change without notice.
Before you begin
Get a key
To use the Maps Embed API, you must include a free API key when making a request to the API.
Follow the instructions in the guide to getting an API key to register your app project on the Google Cloud Platform Console, and get a Google API key to add to your app or website.
Enable billing
NEW: Certain uses of the Maps Embed API are now billed. Before you start developing with the Maps Embed API, review the usage and billing information (you need to enable billing on your project).
Forming the URL
The URL for an Maps Embed API request is as follows:
https://www.google.com/maps/embed/v1/MODE?key=YOUR_API_KEY¶meters
Where:
{MODE}
is one ofplace
,search
,view
,directions
, orstreetview
.{YOUR_API_KEY}
is your free API key.parameters
include optional parameters, as well as mode-specific parameters.
Basic Map Modes
Note: Embed API requests using Place mode or View mode remain free with unlimited usage. See usage and billing for details.
Specify which map mode to use in the request URL.
Place mode
Place
mode displays a map pin at a particular place or address, such as a
landmark, business, geographic feature, or town.
https://www.google.com/maps/embed/v1/place ?key=YOUR_API_KEY &q=Eiffel+Tower,Paris+France
The following URL parameter is required:
q
defines the place to highlight on the map. It accepts a location as either a place name, address, or place ID. The string should be URL-escaped, so an address such as "City Hall, New York, NY" should be converted toCity+Hall,New+York,NY
. (The Maps Embed API supports both+
and%20
when escaping spaces.) Place IDs should be prefixed withplace_id:
.
Attributed Save
A user who is logged into their Google account will be able to save the place
indicated by the q
parameter. Saved places will be visible on other Google
maps on the web or mobile devices. By default, places saved from an
embedded map will include attribution information to remind users where they
were when they saved that place. You can personalize the attribution with the
following parameters.
attribution_source
attributes the save to your site or app. You must include a customattribution_source
before setting eitherattribution_web_url
orattribution_ios_deep_link_id
. Defaults to the URL path of the page on which the map appeared, for example: https://example.com/path/attribution_web_url
specifies a link back to your website. Ifattribution_source
is not specified,attribution_web_url
will default to the URL on which the embedded map appears, for example: https://example.com/path/page.htmlattribution_ios_deep_link_id
specifies a URL Scheme that provides a deep link into an iOS application. When viewed on Google Maps for iOS, theattribution_ios_deep_link_id
will be shown in place of theattribution_web_url
.
The example below displays a pin at the Empress Hotel in Victoria, British Columbia. Saving this location will attribute the save to "Google Maps Embed API". The attribution will appear as a URL. The example makes use of the Google Maps URL Scheme to provide driving directions to iOS Users.
https://www.google.com/maps/embed/v1/place?key=YOUR_API_KEY &q=Fairmont+Empress,Victoria+BC &attribution_source=Google+Maps+Embed+API &attribution_web_url=http://www.fairmont.com/empress-victoria/ &attribution_ios_deep_link_id=comgooglemaps://?daddr=Fairmont+Empress,+Victoria,+BC
View mode
View
mode returns a map with no markers or directions.
The example below uses the optional maptype
parameter to display a
satellite view of the map.
https://www.google.com/maps/embed/v1/view ?key=YOUR_API_KEY ¢er=-33.8569,151.2152 &zoom=18 &maptype=satellite
The following URL parameter is required:
center
defines the center of the map window, and accepts a latitude and a longitude as comma-separated values (-33.8569,151.2152
).
Advanced Map Modes
Note: Embed API requests using Directions mode, Street View mode, or Search mode are billed. See usage and billing for details.
Specify which map mode to use in the request URL.
Directions mode
Directions
mode displays the path between two or more specified points
on the map, as well as the distance and travel time.
https://www.google.com/maps/embed/v1/directions ?key=YOUR_API_KEY &origin=Oslo+Norway &destination=Telemark+Norway &avoid=tolls|highways
The following URL parameters are required:
origin
defines the starting point from which to display directions. The value can be either a place name, address or place ID. The string should be URL-escaped, so an address such as "City Hall, New York, NY" should be converted toCity+Hall,New+York,NY
. (The Maps Embed API supports both+
and%20
when escaping spaces.) Place IDs should be prefixed withplace_id:
.destination
defines the end point of the directions.
The following URL parameters are optional:
waypoints
specifies one or more intermediary places to route directions through between the origin and destination. Multiple waypoints can be specified by using the pipe character (|) to separate places (e.g.Berlin,Germany|Paris,France
). You can specify up to 20 waypoints. Each waypoint can be either a place name, address or place ID.mode
defines the method of travel. Options aredriving
,walking
(which prefers pedestrian paths and sidewalks, where available),bicycling
(which routes via bike paths and preferred streets where available),transit
, orflying
. If no mode is specified, the Maps Embed API will show one or more of the most relevant modes for the specified route.avoid
tells Google Maps to avoidtolls
,ferries
and/orhighways
. Separate multiple values with the pipe character (e.g.avoid=tolls|highways
). Note that this doesn't preclude routes that include the restricted feature(s); it simply biases the result to more favorable routes.units
specifies eithermetric
orimperial
units when displaying distances in the results. Ifunits
are not specified, theorigin
country of the query determines the units to use.
Street View mode
The Maps Embed API lets you display Street View images on your site or blog as interactive panoramas. Google Street View provides panoramic views from designated locations throughout its coverage area. User contributed Photospheres, and Street View special collections are also available.
Each Street View panorama provides a full 360-degree view from a single
location. Images contain 360 degrees of horizontal view (a full wrap-around)
and 180 degrees of vertical view (from straight up to straight down). The
streetview
mode provides a viewer that renders the resulting panorama as a
sphere with a camera at its center. You can manipulate the camera to control
the zoom and the orientation of the camera.
https://www.google.com/maps/embed/v1/streetview ?key=YOUR_API_KEY &location=46.414382,10.013988 &heading=210 &pitch=10 &fov=35
One of the following URL parameters are required:
location
accepts a latitude and a longitude as comma-separated values (46.414382,10.013988
). The API will display the panorama photographed closest to this location. Because Street View imagery is periodically refreshed, and photographs may be taken from slightly different positions each time, it's possible that your location may snap to a different panorama when imagery is updated.pano
is a specific panorama ID. If you specify apano
you may also specify alocation
. Thelocation
will be only be used if the API cannot find the panorama ID.
The following URL parameters are optional:
heading
indicates the compass heading of the camera in degrees clockwise from North. Accepted values are from -180° to 360°.pitch
specifies the angle, up or down, of the camera. Thepitch
is specified in degrees from -90° to 90°. Positive values will angle the camera up, while negative values will angle the camera down. The default pitch of 0° is set based on on the position of the camera when the image was captured. Because of this, a pitch of 0° is often, but not always, horizontal. For example, an image taken on a hill will likely exhibit a default pitch that is not horizontal.fov
determines the horizontal field of view of the image. The field of view is expressed in degrees, with a range of 10° - 100°. It defaults to 90°. When dealing with a fixed-size viewport the field of view is can be considered the zoom level, with smaller numbers indicating a higher level of zoom.language
defines the language to use for UI elements and labels. By default, visitors will see UI elements in their own language.region
defines the appropriate borders and labels to display, based on geo-political sensitivities. Accepts a region code specified as a two-character ccTLD (top-level domain) value.
Search mode
Search
mode displays results for a search across the visible map region.
It's recommended that a location for the search be defined, either by
including a location in the search term (record+stores+in+Seattle
) or
by including a center
and zoom
parameter to bound the search.
https://www.google.com/maps/embed/v1/search ?key=YOUR_API_KEY &q=record+stores+in+Seattle
The following URL parameter is required:
q
specifies the search term. It can include a geographic restriction, such asin+Seattle
ornear+98033
.
Optional parameters
The following optional parameters can be used with any of the map modes listed above.
center
defines the center of the map view. It accepts a comma-separated latitude and longitude value (such as37.4218,-122.0840
).zoom
sets the initial zoom level of the map. Accepted values range from 0 (the whole world) to 21 (individual buildings). The upper limit can vary depending on the map data available at the selected location.maptype
can be eitherroadmap
(the default) orsatellite
, and defines the type of map tiles to load.language
defines the language to use for UI elements and for the display of labels on map tiles. Note that this parameter is only supported for some country tiles; if the specific language requested is not supported for the tile set, then the default language for that tileset will be used. By default, visitors will see a map in their own language.region
defines the appropriate borders and labels to display, based on geo-political sensitivities. Accepts a region code specified as a two-character ccTLD (top-level domain) value.
Place ID parameters
The Maps Embed API supports using place IDs instead of supplying a place name or address. Place IDs are stable way to uniquely identify a place. See the Google Places API documentation for more information on how to find and use place IDs.
The Maps Embed API accepts place IDs for the following URL parameters:
q
origin
destination
waypoints
In order to use a place ID, you must first add the prefix place_id:
. The
following code specifies New York City Hall as the origin for a directions
request: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8
.
radius
sets a radius, specified in meters, in which to search for a panorama, centered on the given latitude and longitude. Valid values are non-negative integers. Default value is 50.source
limits Street View searches to selected sources. Valid values are:default
uses the default sources for Street View; searches are not limited to specific sources.outdoor
limits searches to outdoor collections. Indoor collections are not included in search results. Note that outdoor panoramas may not exist for the specified location. Also note that the search only returns panoramas where it's possible to determine whether they're indoors or outdoors. For example, PhotoSpheres are not returned because it's unknown whether they are indoors or outdoors.
Embedding the map
To use the Maps Embed API on your web page, set the URL you've
built as the value of an iframe's src
attribute. Control the map's size with
the iframe's height
and width
attributes:
<iframe width="450" height="250" frameborder="0" style="border:0" src="https://www.google.com/maps/embed/v1/search?key=YOUR_API_KEY&q=record+stores+in+Seattle" allowfullscreen> </iframe>
Tip: Add allowfullscreen to your iframe properties to allow
certain map parts to go full screen.
Tip: The frameborder="0"
and style="border:0"
properties
remove the standard iframe border from around the map.
You can resize the iframe to suit the structure and design of your own website, but we find that visitors usually find it easier to interact with larger maps. Note that embedded maps are not supported below a size of 200px in either dimension.
Usage statistics
For users of Maps Embed API, Google uses cookies to determine the number of unique users of the API. Signed-in users are identified by their Google cookie, which is also used to provide a personalised experience. For users that are not signed in, Google uses an anonymous cookie for each unique user.
Google also accumulates statistics about the types of features used from the Maps product.