本指南說明如何在網頁中嵌入互動式地圖。
建立 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="no-referrer-when-downgrade"
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="no-referrer-when-downgrade"屬性可讓瀏覽器將完整網址做為Referer標頭與要求一起傳送，以便 API 金鑰限制正常運作。
您可以根據網站的結構和設計調整 iframe 大小，但我們發現訪客通常會更偏好較大的地圖。請注意，嵌入地圖的大小不得低於任何一維度 200 像素。
API 金鑰限制
如果代管網站的 referrer 中繼標記設為 no-referrer 或 same-origin，瀏覽器就不會將 Referer 標頭傳送給 Google。這可能會導致您的 API 金鑰限制拒絕要求。為了讓限制條件正常運作，請如上例所示，在 iframe 中加入 referrerpolicy 屬性，明確允許將 Referer 標頭傳送給 Google。
地圖上的廣告
Maps Embed API 可能會加入地圖上的廣告。我們可能會在未事先通知的情況下，變更任何地圖中顯示的廣告格式和廣告組合。
選擇地圖模式
您可以在要求網址中指定下列其中一種地圖模式：
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 |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 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 |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 兩位字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
directions模式
以下範例使用 directions 模式，顯示挪威 Oslow 和 Telemark 之間的路徑、距離，以及避開收費和高速公路的車程時間。
https://www.google.com/maps/embed/v1/directions
?key=YOUR_API_KEY
&origin=Oslo+Norway
&destination=Telemark+Norway
&avoid=tolls|highways您可以使用下列參數：
| 參數 | 類型 | 說明 | 接受的值 |
|---|---|---|---|
origin |
必要 | 定義路線起點。 | 經過網址轉義處理的地點名稱、地址、加號代碼、經緯度座標或地點 ID。在轉義空格時，Maps Embed API 支援 + 和 %20。例如將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或將 Plus Code「849VCWC8+R9」轉換為 849VCWC8%2BR9。 |
destination |
必要 | 定義路線的終點。 | 經過網址轉義處理的地點名稱、地址、加號代碼、經緯度座標或地點 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 |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 兩位字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
streetview模式
透過 Maps Embed API，您可以在涵蓋區域內的指定位置，將街景服務圖片顯示為互動式全景。您也可以使用使用者提供的 Photosphere 相片和街景服務特輯集合。
每個街景服務全景都提供單一位置的 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 |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 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 |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受區碼，指定為兩位字元 (非數字) 萬國碼區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 兩位字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。 |
地點 ID 參數
Maps Embed API 支援使用地點 ID，而非提供地點名稱或地址。地點 ID 是用來識別特定地點的穩定方法。詳情請參閱 Google Places API 說明文件。
Maps Embed API 接受下列網址參數的地點 ID：
qorigindestinationwaypoints
如要使用地點 ID，您必須先新增前置字串 place_id:。以下程式碼將紐約市政廳指定為路線要求 origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8 的起點。
radius會設定半徑 (以公尺為單位)，以指定經緯度為中心搜尋全景。有效值為非負整數。預設值為 50。source會將街景服務搜尋範圍限制在所選來源。有效值如下：default會使用街景服務的預設來源。搜尋範圍不限於特定來源。outdoor會將搜尋範圍限制在室外集錦。室內收藏品不會列入搜尋結果。請注意，室外全景可能不適用於特定位置。請注意，搜尋結果只會傳回可判斷是否為室內或室外的全景圖。舉例來說，系統不會傳回 PhotoSphere，因為無法判斷該相片是在室內或室外拍攝。