嵌入地圖

本指南說明如何在網頁中嵌入互動式地圖。

建立 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 地圖模式，在艾菲爾鐵塔上顯示地圖標記：

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
  &center=-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：

  • q
  • origin
  • destination
  • waypoints

如要使用地點 ID，您必須先新增前置字串 place_id:。以下程式碼將紐約市政廳指定為路線要求 origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8 的起點。

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

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

    • default 會使用街景服務的預設來源。搜尋範圍不限於特定來源。
    • outdoor 會將搜尋範圍限制在室外集錦。室內收藏品不會列入搜尋結果。請注意，室外全景可能不適用於特定位置。請注意，搜尋結果只會傳回可判斷是否為室內或室外的全景圖。舉例來說，系統不會傳回 PhotoSphere，因為無法判斷該攝影機是否在室內或室外。