嵌入地圖

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

建立 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 的 heightwidth 屬性控制地圖大小,例如:

<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-referrersame-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,也可以將代碼「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
  &center=-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 模式,顯示挪威奧斯洛和 Telemark、挪威、距離和避開收費路段和高速公路之間的路徑。

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,也可以將代碼「849VCWC8+R9」轉換為 849VCWC8%2BR9
destination 必要 定義路線的終點。 網址逸出的地點名稱、地址、plus code、經緯度座標或地點 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 會顯示指定路線的一或多個最相關的模式。 drivingwalking (建議使用人行道和人行道,如果可使用)、bicycling (可能設有單車道和專用道路的路線)、transitflying
avoid 選用 指定要在路線中避免的功能。請注意,雖然路徑並未排除內含受限地圖項目的路徑,而是會將結果調整成較偏好的路線。 tollsferries 和/或 highways。 請使用直立線字元分隔多個值 (例如 avoid=tolls|highways)。
units 選用 在結果中顯示距離時,指定測量方法、公製或英制。如未指定 units,系統會使用查詢的 origin 國家/地區來決定要使用的單位。 metricimperial
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) 中加入地點,或是加入 centerzoom 參數來限定搜尋範圍,藉此定義搜尋的位置。

https://www.google.com/maps/embed/v1/search
  ?key=YOUR_API_KEY
  &q=record+stores+in+Seattle

您可以使用下列參數:

參數 類型 說明 接受的值
q 必要 用於定義搜尋字詞, 可包含地理區域限制,例如 in+Seattlenear+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,因為它們無論在室內或室外。