本指南說明如何在網頁中嵌入互動式地圖。
建立 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 Codes「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 (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值如需支援區域的相關資訊，請參閱 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 |
必要 | 定義路線的起點。 | 經過網址轉義處理的地點名稱、地址、加號代碼、經緯度座標或地點 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，您可以在涵蓋區域內的指定位置，將街景服務圖片顯示為互動式全景。使用者 貢獻的全景相片，以及 街景服務集錦 您也可以使用
每個街景服務全景都提供單一位置的 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° 不一定每次都是橫向舉例來說，從山丘上拍攝的圖片 會顯示非水平的預設傾斜角度。 | 以度為單位的值，範圍從 -90° 到 90° |
fov |
選用 | 會決定圖片的水平視野。這項服務 預設為 90°。處理固定大小的可視區域時 系統會將視圖視為縮放等級，較小的數字表示 | 以度為單位的數值，範圍介於 10° - 100° |
center |
選用 | 定義地圖檢視的中心。 | 接受以半形逗號分隔的經緯度值；例如：
37.4218,-122.0840。 |
zoom |
選用 | 設定地圖的初始縮放等級。 | 值的範圍從 0 (全世界) 到 21 (個別建築物)。上限會因所選位置的可用地圖資料而異。 |
maptype |
選用 | 定義要載入的地圖圖塊類型。 | roadmap (預設) 或 satellite |
language |
選用 | 定義 UI 元素和顯示 標籤上。根據預設，訪客可以自行建立地圖 語言。這個參數僅適用於部分國家/地區圖塊；如果 方塊集不支援您要求的特定語言，那麼 該方塊集的預設語言。 | |
region |
選用 | 根據地緣政治敏感度，定義要顯示的適當邊框和標籤。 | 接受指定為雙字元 (非數字) 的區碼 與熟悉 ccTLD (「頂層網域」) 對應的 Unicode 區域子標記 兩個字元的值如需支援區域的相關資訊，請參閱 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，因為無法判斷該相片是在室內或室外拍攝。