本指南說明如何在網頁中嵌入互動式地圖。
建立 Maps Embed API 網址
以下是載入 Maps Embed API 的網址範例：
https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS
更改項目：
將網址加入 iframe
如要在網頁上使用 Maps Embed API，請將建立的網址設為 iframe 的 src 屬性值。使用 iframe 的 height 和 width 屬性控制地圖大小，例如：
<iframe
width="450"
height="250"
frameborder="0" style="border:0"
referrerpolicy="strict-origin-when-cross-origin"
src="https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS"
allowfullscreen>
</iframe>上述 iframe 範例使用下列額外屬性：
allowfullscreen屬性：允許地圖的特定部分進入全螢幕模式。frameborder="0"和style="border:0"屬性，用於移除地圖周圍的標準 iframe 邊框。referrerpolicy="strict-origin-when-cross-origin"屬性可確保瀏覽器將網站網域做為Referer標頭傳送至 Google。這樣一來，API 金鑰限制就能驗證要求，同時確保特定網頁路徑不公開。
您可以調整 iframe 大小，以符合網站的結構和設計，但我們發現，訪客通常比較容易與較大的地圖互動。請注意，嵌入地圖的任一維度大小不得小於 200 像素。
參照網址資訊和 API 金鑰限制
如果代管網站的 referrer 中繼標記設為 no-referrer 或 same-origin，瀏覽器就不會將 Referer 標頭傳送給 Google。這可能會導致 API 金鑰限制拒絕要求。為確保限制功能正常運作，請在 iframe 中加入 referrerpolicy 屬性 (如上例所示)，明確允許將 Referer 標頭傳送至 Google。
strict-origin-when-cross-origin(建議)：只將基礎網域 (例如 https://example.com/) 傳送給 Google。這樣一來，特定網頁路徑就不會公開，API 金鑰限制也能正常運作。no-referrer-when-downgrade(舊版)：傳送完整網址，包括特定網頁路徑和查詢參數 (例如 https://example.com/contact?user=123)。
選擇地圖模式
您可以在要求網址中指定下列其中一種地圖模式：
place：在地標、商家、地貌或城鎮等特定地點或地址，顯示地圖圖釘。view：傳回沒有標記或路線的地圖。directions：在地圖上顯示兩個或多個指定點之間的路徑，以及距離和行程時間。streetview：顯示指定位置的互動式全景。search：顯示可見地圖區域的搜尋結果。
place模式
下列網址使用 place 地圖模式，在艾菲爾鐵塔顯示地圖標記：
https://www.google.com/maps/embed/v1/place
?key=YOUR_API_KEY
&q=Eiffel+Tower,Paris+France您可以使用下列參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
q |
必要 | 定義地圖標記位置。 | 經過網址逸出的地點名稱、地址、Plus Code 或地點 ID。
Maps Embed API 支援使用 + 和 %20 逸出空格。舉例來說，將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或將 Plus Code「849VCWC8+R9」轉換為 849VCWC8%2BR9。 |
center |
選用 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值介於 0 (整個世界) 到 21 (個別建築物) 之間。上限可能會因所選位置的地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和地圖圖塊標籤顯示時使用的語言。根據預設，訪客會看到以其語言顯示的地圖。這項參數僅適用於部分國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊界和標籤。 | 接受指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
view模式
以下範例使用 view 模式和選用的 maptype 參數，顯示地圖的衛星檢視畫面：
https://www.google.com/maps/embed/v1/view
?key=YOUR_API_KEY
¢er=-33.8569,151.2152
&zoom=18
&maptype=satellite您可以使用下列參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
center |
必要 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值介於 0 (整個世界) 到 21 (個別建築物) 之間。上限可能會因所選位置的地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和地圖圖塊標籤顯示時使用的語言。根據預設，訪客會看到以其語言顯示的地圖。這項參數僅適用於部分國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊界和標籤。 | 接受指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
directions模式
以下範例使用 directions 模式，顯示挪威奧斯陸和泰勒馬克之間的路線、距離和行程時間，並避開收費路段和高速公路。
https://www.google.com/maps/embed/v1/directions
?key=YOUR_API_KEY
&origin=Oslo+Norway
&destination=Telemark+Norway
&avoid=tolls|highways您可以使用下列參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
origin |
必要 | 定義顯示路線的起點。 | 經過網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。Maps Embed API 支援 + 和 %20 兩種空格逸出方式。舉例來說，將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或將 Plus Code「849VCWC8+R9」轉換為 849VCWC8%2BR9。 |
destination |
必要 | 定義路線的終點。 | 經過網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。Maps Embed API 支援使用 + 和 %20 逸出空格。舉例來說，將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或將 Plus Code「849VCWC8+R9」轉換為 849VCWC8%2BR9。 |
waypoints |
選用 | 指定一或多個中繼地點，用於規劃起點和目的地之間的路線。 | 地點名稱、地址或地點 ID。
如要指定多個路線控點，請使用直立線字元 (|) 分隔地點 (例如 Berlin,Germany|Paris,France)。最多可指定 20 個路線控點。 |
mode |
選用 | 定義移動方式。如果未指定模式，Maps Embed API 會顯示一或多個與指定路線最相關的模式。 | driving、walking (優先選擇行人步道和人行道，如有)、bicycling (優先選擇設有單車道和專用道路的路線，如有)、transit 或 flying。 |
avoid |
選用 | 指定路線中應避開的特徵。請注意，這不會排除包含受限特徵的路線，而是會優先顯示更合適的路線。 | tolls、ferries和/或highways。
如有多個值，請以直立線字元分隔 (例如 avoid=tolls|highways)。 |
units |
選用 | 指定在結果中顯示距離時，要使用公制或英制測量方法。如未指定 units，系統會根據查詢的 origin 國家/地區決定要使用的單位。 |
metric 或 imperial |
center |
選用 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值介於 0 (整個世界) 到 21 (個別建築物) 之間。上限可能會因所選位置的地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和地圖圖塊標籤顯示時使用的語言。根據預設，訪客會看到以其語言顯示的地圖。這項參數僅適用於部分國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊界和標籤。 | 接受指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
streetview模式
Maps Embed API 可讓您在涵蓋區域內，以互動式全景的形式顯示指定位置的街景服務圖像。此外，您也可以使用使用者提供的相片球和街景服務特殊集錦。
每個街景服務全景都提供單一位置的 360 度完整環景。圖片包含 360 度的水平視圖 (完整的環景) 與 180 度的垂直視圖 (由正上方到正下方)。streetview 模式提供的檢視器會將全景算繪為球體，攝影機則位於其中央。您可以操控攝影機，控制攝影機的縮放及方向。
請參閱以下 streetview 模式全景：
https://www.google.com/maps/embed/v1/streetview
?key=YOUR_API_KEY
&location=46.414382,10.013988
&heading=210
&pitch=10
&fov=35必須提供下列其中一個網址參數：
location接受以逗號分隔值 (46.414382,10.013988) 表示的經緯度。API 會顯示最靠近這個位置拍攝的全景。由於街景服務圖像會定期更新，且每次拍攝的位置可能略有不同，因此在圖像更新時，您的位置可能會貼齊不同的全景。pano是特定全景 ID。如果指定pano，也可以指定location。只有在 API 找不到全景 ID 時，才會使用location。
以下是選用網址參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
heading |
選用 | 表示攝影機的指南針方向，以北為基準，依順時針方向測量。 | 值介於 -180° 到 360° 之間 |
pitch |
選用 | 指定攝影機的上下角度。正值會使攝影機向上傾斜，負值則會使攝影機向下傾斜。預設俯仰角為 0°，是根據拍攝圖片時的攝影機位置設定。因此，0° 的俯仰角通常 (但不一定) 是水平。舉例來說，如果圖片是從山丘上拍攝，其預設傾斜角度可能就不是水平。 | 值介於 -90° 到 90° 之間 |
fov |
選用 | 決定圖片的水平視野。預設值為 90°。處理固定大小的可視區域時，視野可視為縮放等級，數字越小表示縮放等級越高。 | 值以度為單位，範圍為 10° - 100° |
center |
選用 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值介於 0 (整個世界) 到 21 (個別建築物) 之間。上限可能會因所選位置的地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和地圖圖塊標籤顯示時使用的語言。根據預設，訪客會看到以其語言顯示的地圖。這項參數僅適用於部分國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊界和標籤。 | 接受指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
search模式
Search 模式會顯示可見地圖區域的搜尋結果。建議您定義搜尋位置，方法是在搜尋字詞 (record+stores+in+Seattle) 中加入位置，或加入 center 和 zoom 參數來限制搜尋範圍。
https://www.google.com/maps/embed/v1/search
?key=YOUR_API_KEY
&q=record+stores+in+Seattle您可以使用下列參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
q |
必要 | 定義搜尋字詞。 | 可以包含地理限制，例如 in+Seattle 或 near+98033。 |
center |
選用 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值介於 0 (整個世界) 到 21 (個別建築物) 之間。上限可能會因所選位置的地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和地圖圖塊標籤顯示時使用的語言。根據預設，訪客會看到以其語言顯示的地圖。這項參數僅適用於部分國家/地區圖塊；如果圖塊集不支援要求的特定語言，系統會使用該圖塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊界和標籤。 | 接受指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
地點 ID 參數
Maps Embed API 支援使用地點 ID，而非提供地點名稱或地址。地點 ID 是用來識別特定地點的穩定方式。詳情請參閱 Places API (新版) 說明文件。
Maps Embed API 接受下列網址參數的地點 ID：
qorigindestinationwaypoints
如要使用地點 ID，請先加上前置字串 place_id:。下列程式碼將紐約市政廳指定為路線規劃要求的起點：origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8。
radius會設定半徑 (以公尺為單位)，以指定經緯度為中心搜尋全景。有效值為非負整數。預設值為 50。source會將街景服務搜尋範圍限制在所選來源。有效值如下：default會使用街景服務的預設來源。搜尋範圍不限於特定來源。outdoor會將搜尋範圍限制在室外集錦。室內集錦不會顯示在搜尋結果中。請注意，室外全景可能不適用於特定位置。另請注意，搜尋只會傳回可判斷室內或室外的全景。舉例來說，系統不會傳回 PhotoSphere，因為無法判斷是在室內或室外。