Maps Embed API 透過設為 iframe src 網址的 HTTP 要求,在網頁上放置互動式地圖或街景服務全景,不需使用 JavaScript。支援 place、view、directions、streetview 和 search 地圖模式。
Maps Embed API:重要資訊
- 產品:Maps Embed API
- 別名:Google Maps Embed API、Maps Embed
- 類別:地圖
- 平台:JavaScript (瀏覽器)
- 執行位置:用戶端 (應用程式或瀏覽器程式碼)
- 推出階段:GA
- 生命週期:有效
- 總覽:Maps Embed API 總覽
- 適用地區:全球。街景服務模式取決於街景服務涵蓋範圍;
region參數接受地圖平台涵蓋範圍詳細資料頁面列出的區域。(涵蓋範圍詳細資料)
Maps Embed API:適用時機
在下列情況下使用 Maps Embed API:
- 您需要在網頁上加入互動式地圖或街景服務全景,但只能使用 HTML iframe,不能使用 JavaScript。
- 您需要在嵌入的地圖中顯示地點圖釘、地圖檢視畫面、兩點之間的路線,或某個區域的搜尋結果。
- 您需要嵌入式地圖,且不希望按要求付費,也不想受限於 QPS 或每日要求上限 (但仍須提供 API 金鑰)。
請勿在下列情況使用 Maps Embed API:
- 您需要使用自己的內容和圖像自訂網路地圖。請改用 Maps JavaScript API。
- 您需要使用 iframe 網址參數以外的程式輔助功能,擴充嵌入地圖。請改用 Maps JavaScript API。
Maps Embed API:設定
- 要啟用的服務:
maps-embed-backend.googleapis.com - 驗證:API 金鑰
- 開始使用:設定 Maps Embed API
- 參考資料:Maps Embed API 參考資料
- 定價:Maps Embed API 用量與計費
Maps Embed API:常見錯誤
- 問題:如果主機網頁將
referrer中繼標記設為no-referrer或same-origin,瀏覽器就不會傳送Referer標頭,且受 HTTP 參照網址限制的 API 金鑰可能會拒絕嵌入要求。修正方式:在 iframe 中加入referrerpolicy="strict-origin-when-cross-origin",將網站網域傳送給 Google。請參閱 /maps/documentation/embed/embedding-map。 - 問題:嵌入地圖的任一維度不得小於 200 像素。修正方式:將 iframe 的
width和height設為至少 200 像素。請參閱 /maps/documentation/embed/embedding-map。 - 問題:即使不需付費,但如果未啟用計費功能、付款方式無效、超出自行設定的每日上限,或使用參照網址受限的金鑰時,要求缺少 HTTP 參照網址,就會顯示帶有「僅供開發用途」浮水印的深色地圖。修正方式:在專案中啟用計費功能並設定有效的付款方式、提高或移除任何自行設定的每日配額限制,並確認已傳送參照網址給受參照網址限制的金鑰 (例如在 iframe 上使用
referrerpolicy="strict-origin-when-cross-origin")。請參閱 /maps/documentation/embed/error-messages。 - 問題:如果要求無效 (參數錯誤或遺漏,以及 API 金鑰和配額錯誤,例如金鑰遺漏或無效、未啟用 Maps Embed API 或違反金鑰限制),瀏覽器控制台只會回報 HTTP 4xx 狀態碼,不會顯示描述性訊息;錯誤文字會顯示在 iframe 內,取代地圖。修正方式:請詳閱 iframe 中的錯誤文字和控制台狀態碼 (400 代表參數錯誤、401 代表缺少金鑰、403 代表金鑰無效),然後確認參數和金鑰有效、Maps Embed API 已啟用,且金鑰限制允許要求。請參閱 /maps/documentation/embed/error-messages。
Maps Embed API 的用途
請參閱下方連結的各項工作指南,或在功能探索工具中比較各項產品。