本指南說明如何在您的網頁中嵌入互動式地圖。
建立 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, NY, 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
¢er=-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
模式顯示奧斯洛和電信、挪威、距離,以及避開收費路段和高速公路的所需時間。
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, NY, NY」轉換為 City+Hall,New+York,NY ,或將代碼「849VCWC8+R9」轉換為 849VCWC8%2BR9 。 |
destination |
必要 | 定義路線的終點。 | 網址逸出的地點名稱、地址、Plus Code、經緯度座標或地點 ID。逸出聊天室時,Maps Embed API 支援 + 和 %20 。例如,將「City Hall, NY, 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
模式全景:
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
) 或加入 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 |
選用 | 根據地緣政治敏感度,定義適當的邊界和標籤。 | 接受以雙字元 (非數字) 萬國碼 (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
會將搜尋範圍限制在室外集錦。搜尋結果不會包含室內集合。請注意,室外全景可能不適用於特定位置。此外請注意,搜尋作業只會在可能的情況下傳回全景,以判斷圖片為室內或室外。舉例來說,系統不會傳回 PhotoSphere,因為無論在室內還是室外都不明。