本指南說明如何在網頁中嵌入互動式地圖。
建立 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 ,也可以將代碼「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
模式,顯示挪威奧斯洛和 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 會顯示指定路線的一或多個最相關的模式。 | 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
會將搜尋範圍限制在室外集錦。搜尋結果不會包含室內集合。請注意,室外全景可能不適用於特定位置。此外請注意,搜尋只會傳回可判斷其位於室內或室外的全景。舉例來說,系統不會傳回 PhotoSpheres,因為它們無論在室內或室外。