Maps Embed API quick reference

Maps Embed API places an interactive map or Street View panorama on a web page through an HTTP request set as an iframe src URL, with no JavaScript required. It supports place, view, directions, streetview, and search map modes.

Maps Embed API: key facts

  • Product: Maps Embed API
  • Also known as: Google Maps Embed API, Maps Embed
  • Category: Maps
  • Platform: JavaScript (browser)
  • Runs on: Client (app or browser code)
  • Launch stage: GA
  • Lifecycle: Active
  • Overview: Maps Embed API overview
  • Regional availability: Global. Street View mode depends on Street View coverage; the region parameter accepts regions listed on the Maps Platform coverage details page. (coverage details)

Maps Embed API: when to use it

Use Maps Embed API when:

  • You need an interactive map or Street View panorama on a web page using only an HTML iframe, with no JavaScript.
  • You need to show a place pin, a map view, directions between points, or search results for an area in an embedded map.
  • You need an embedded map with no per-request charge and no QPS or daily request limits (an API key is still required).

Don't use Maps Embed API when:

  • You need to customize a web map with your own content and imagery. Use Maps JavaScript API instead.
  • You need to extend an embedded map with programmatic features beyond the iframe URL parameters. Use Maps JavaScript API instead.

Maps Embed API: setup

Maps Embed API: common mistakes

  • Problem: If the host page sets a referrer meta tag to no-referrer or same-origin, the browser doesn't send the Referer header, and an HTTP-referrer-restricted API key can reject the embed requests. Fix: Add referrerpolicy="strict-origin-when-cross-origin" to the iframe so the site's domain is sent to Google. See /maps/documentation/embed/embedding-map.
  • Problem: Embedded maps aren't supported below 200 px in either dimension. Fix: Set the iframe width and height to at least 200 px. See /maps/documentation/embed/embedding-map.
  • Problem: Even though usage is at no charge, a darkened map watermarked "for development purposes only" appears if billing isn't enabled, the billing method is invalid, a self-imposed daily limit is exceeded, or the request lacks an HTTP referer while using a referer-restricted key. Fix: Enable billing with a valid payment method on the project, raise or remove any self-imposed daily quota limit, and make sure the referer is sent for referer-restricted keys (for example, with referrerpolicy="strict-origin-when-cross-origin" on the iframe). See /maps/documentation/embed/error-messages.
  • Problem: For invalid requests (bad or missing parameters, and API key and quota errors such as a missing or invalid key, the Maps Embed API not being enabled, or a key restriction violation), only the HTTP 4xx status code is reported in the browser console, not a descriptive message; the error text appears inside the iframe in place of the map. Fix: Read the error text in the iframe and the console status code (400 for parameter errors, 401 for a missing key, 403 for an invalid key), then confirm the parameters are valid, the key is valid, the Maps Embed API is enabled, and the key restrictions allow the request. See /maps/documentation/embed/error-messages.

What you can do with Maps Embed API

See the guides linked below for each task, or compare across products in the Capabilities Explorer.

Maps Embed API: Directions and Routing

Maps Embed API: Maps

Maps Embed API: Places

Maps Embed API: Street View