Hide
Google Maps Embed API

Google Maps Embed API

Overview

The Google 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 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=API_KEY
    &q=Space+Needle,Seattle+WA">
</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

Google 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.

No usage limits

There are no usage limits for the Maps Embed API. You can embed maps or Street View panoramas on your high-traffic websites without fear of hitting a usage cap or query-per-second throttling.

Advertisements on the map

The Google Maps Embed API includes on-map advertising. The advertisements look similar to those currently experienced on Google Maps and on Google Maps for Mobile. Here is an example:

An embedded map with an ad

Forming the URL

The URL for an Embed API request is as follows:

https://www.google.com/maps/embed/v1/MODE?key=API_KEY&parameters

Where:

  • {MODE} is one of place, directions, search, view, or streetview.
  • {API_KEY} is your free API key.
  • parameters include optional parameters, as well as mode-specific parameters.

API key

All requests to the Embed API must include a free API key as the value of a key parameter. Your key enables you to monitor your application's Maps API usage, and ensures that Google can contact you about your website/application if necessary.

To retrieve your API key:

  1. Visit the APIs Console at Google Developers Console and log in with your Google Account.
  2. Click the Services link from the left-hand menu.
  3. Activate the Google Maps Embed API service.
  4. Click the API Access link from the left-hand menu. Your API key is available from the API Access page, in the Simple API Access section. Maps API applications use the Key for browser apps.

By default, a key can be used on any site. We strongly recommend that you restrict the use of your key to domains that you administer, to prevent use on unauthorized sites. You can specify which domains are allowed to use your API key by clicking the Edit allowed referrers... link for your key.

Your API key looks something like this: AIzaSyCwI3k7JC29_KzlX1S_bC8fARpocLX5bRY

Map Modes

There are four map embed modes available to you. The mode is specified 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=API_KEY
  &q=Fisht+Olympic+Stadium,Sochi+Russia

The following URL parameter is required:

  • q defines the place to highlight on the map. It accepts a location as either a place name or address. The string should be URL-escaped, so an address such as "City Hall, New York, NY" should be converted to City+Hall,New+York,NY. (The Google Maps Embed API supports both + and %20 when escaping spaces.)

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 custom attribution_source before setting either attribution_web_url or attribution_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. If attribution_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.html
  • attribution_ios_deep_link_id specifies a URL Scheme that provides a deep link into an iOS application. When viewed on Google Maps for iOS, the attribution_ios_deep_link_id will be shown in place of the attribution_web_url.

The below example displays a pin at Butchart Gardens 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.

  <iframe
    width="600"
    height="450"
    frameborder="0" style="border:0"
    src="https://www.google.com/maps/embed/v1/place?key=API_KEY
      &q=Butchart+Gardens+Victoria+BC
      &attribution_source=Google+Maps+Embed+API
      &attribution_web_url=http://www.butchartgardens.com/
      &attribution_ios_deep_link_id=comgooglemaps://?daddr=Butchart+Gardens+Victoria+BC">
  </iframe>

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=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 or address. The string should be URL-escaped, so an address such as "City Hall, New York, NY" should be converted to City+Hall,New+York,NY. (The Google Maps Embed API supports both + and %20 when escaping spaces.)
  • 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.
  • mode defines the method of travel. Options are driving, walking (which prefers pedestrian paths and sidewalks, where available), bicycling (which routes via bike paths and preferred streets where available), transit, or flying. If no mode is specified, the Embed API will show one or more of the most relevant modes for the specified route.
  • avoid tells Google Maps to avoid tolls, ferries and/or highways. 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 either metric or imperial units when displaying distances in the results. If units are not specified, the origin country of the query determines the units to use.

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=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 as in+Seattle or near+98033.

View mode

View mode returns a map with no markers or directions.

https://www.google.com/maps/embed/v1/view
  ?key=API_KEY
  &center=-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).

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 as 37.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 either roadmap (the default) or satellite, 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.

Street View mode

The Google 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=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 a pano you may also specify a location. The location 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&deg.

  • pitch specifies the angle, up or down, of the camera. The pitch 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.

Embedding the map

To use the 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=API_KEY&q=record+stores+in+Seattle">
</iframe>

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.