嵌入地圖

本指南說明如何將互動式地圖嵌入您的網頁。

建立 Maps Embed API 網址

以下是載入 Maps Embed API 的網址範例：

https://www.google.com/maps/embed/v1/MAP_MODE?key=YOUR_API_KEY&PARAMETERS

取代下列項目：

• MAP_MODE 搭配地圖模式。
• 將 YOUR_API_KEY 替換成您的 API 金鑰。詳情請參閱「取得 API 金鑰」一文。
• 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 地圖模式，在艾菲爾鐵塔顯示地圖標記：

您可以使用下列參數：

參數	類型	說明	接受的值
q	必要	定義地圖標記位置。	網址逸出的地點名稱、地址、Plus Code 或地點 ID。在封裝空格時，Maps Embed API 同時支援 + 和 %20。舉例來說，您可以將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或另外將「849VCWC8+R9」代碼轉換為 849VCWC8%2BR9。
center	選用	定義地圖檢視的中心點。	可接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom	選用	設定地圖的初始縮放等級。	範圍從 0 (全球) 到 21 (個別建築物)。數量上限視所選地點提供的地圖資料而定。
maptype	選用	定義要載入的地圖圖塊類型。	roadmap (預設) 或 satellite
language	選用	定義 UI 元素要使用的語言，以及地圖圖塊上的標籤。根據預設，訪客必須使用自己的語言查看地圖。這個參數僅適用於部分國家/地區；如果圖塊設定不支援特定語言，系統就會使用該圖塊的預設語言。
region	選用	根據地理政治敏感度定義，定義要顯示的適當邊框和標籤。	接受的區域代碼，必須是雙字元 (非數字) 萬國碼 (Unicode) 區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。

view模式

以下範例使用 view 模式和選用的 maptype 參數來顯示地圖的衛星檢視：

您可以使用下列參數：

參數	類型	說明	接受的值
center	必要	定義地圖檢視的中心點。	可接受以半形逗號分隔的經緯度值，例如：37.4218,-122.0840。
zoom	選用	設定地圖的初始縮放等級。	範圍從 0 (全球) 到 21 (個別建築物)。數量上限視所選地點提供的地圖資料而定。
maptype	選用	定義要載入的地圖圖塊類型。	roadmap (預設) 或 satellite
language	選用	定義 UI 元素要使用的語言，以及地圖圖塊上的標籤。根據預設，訪客必須使用自己的語言查看地圖。這個參數僅適用於部分國家/地區；如果圖塊設定不支援特定語言，系統就會使用該圖塊的預設語言。
region	選用	根據地理政治敏感度定義，定義要顯示的適當邊框和標籤。	接受的區域代碼，必須是雙字元 (非數字) 萬國碼 (Unicode) 區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。

directions模式

以下範例使用 directions 模式，顯示奧斯羅和望爾維線、挪威、距離和交通時間之間的路線，避開收費路段和高速公路。

您可以使用下列參數：

參數	類型	說明	接受的值
origin	必要	定義顯示路線的起點。	網址逸出的地點名稱、地址、加號、緯度/經度座標或地點 ID。在封裝空格時，Maps Embed API 同時支援 + 和 %20。舉例來說，您可以將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或另外將「849VCWC8+R9」代碼轉換為 849VCWC8%2BR9。
destination	必要	定義路線的終點。	網址逸出的地點名稱、地址、加號、緯度/經度座標或地點 ID。在封裝空格時，Maps Embed API 同時支援 + 和 %20。舉例來說，您可以將「City Hall, New York, NY」轉換為 City+Hall,New+York,NY，或另外將「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 模式全景：

「必須」選擇下列任一網址參數：

• 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	選用	根據地理政治敏感度定義，定義要顯示的適當邊框和標籤。	接受的區域代碼，必須是雙字元 (非數字) 萬國碼 (Unicode) 區域子標記，對應至熟悉的 ccTLD (「頂層網域」) 雙字元值。如需支援區域的相關資訊，請參閱 Google 地圖平台涵蓋範圍詳細資料。

search模式

Search 模式會在搜尋地圖區域顯示搜尋結果。建議在搜尋中加入位置，方法是在搜尋字詞中加入位置 (record+stores+in+Seattle)，或加入 center 和 zoom 參數來繫結搜尋。

您可以使用下列參數：

參數	類型	說明	接受的值
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 可明確識別特定地點。詳情請參閱 Google Places API 說明文件。

Maps Embed API 接受下列網址參數的地點 ID：

• q
• origin
• destination
• waypoints

如要使用地點 ID，您必須先新增前置字串 place_id:。以下程式碼將紐約市城市做為路線規劃要求的來源：origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8。

• radius 會設定半徑 (以公尺為單位)，以指定經緯度為中心搜尋全景。有效值是非負整數。預設值為 50。

• source 會將街景服務的搜尋範圍限制在所選的來源。以下為有效值：

  • default 會使用街景服務的預設來源。搜尋範圍不限於特定來源。
  • outdoor 會將搜尋範圍限制在室外集錦。不包含室內集錦。請注意，室外全景可能不適用於特定位置。另請注意，搜尋只會傳回可判斷是室內或戶外的全景。舉例來說，系統不會傳回 PhotoSpheres，因為相片不明或室內。