Nhúng bản đồ

Hướng dẫn này cho biết cách nhúng bản đồ tương tác vào trang web của bạn.

Tạo URL của API Nhúng của Maps

Sau đây là một URL mẫu tải API Nhúng của Maps:

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

Thay thế:

  • MAP_MODE với chế độ bản đồ của bạn.
  • YOUR_API_KEY bằng khoá API. Để biết thêm thông tin, hãy xem bài viết Lấy khoá API.
  • PARAMETERS với các tham số bắt buộc và không bắt buộc cho chế độ bản đồ.

Thêm URL vào iframe

Để sử dụng API Nhúng của Maps trên trang web của bạn, hãy đặt URL bạn đã tạo làm giá trị của thuộc tính src của iframe. Kiểm soát kích thước của bản đồ bằng các thuộc tính heightwidth của iframe, ví dụ:

<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>

Mẫu iframe ở trên sử dụng các thuộc tính bổ sung:

  • Thuộc tính allowfullscreen để cho phép một số phần bản đồ nhất định hiển thị toàn màn hình.
  • Các thuộc tính frameborder="0"style="border:0" để xoá đường viền iframe chuẩn khỏi xung quanh bản đồ.
  • Thuộc tính referrerpolicy="no-referrer-when-downgrade" để cho phép trình duyệt gửi URL đầy đủ dưới dạng tiêu đề Referer kèm theo yêu cầu để các quy định hạn chế về khoá API có thể hoạt động đúng cách.

Bạn có thể đổi kích thước iframe cho phù hợp với cấu trúc và thiết kế trang web của mình, nhưng chúng tôi thấy rằng khách truy cập thường thấy dễ dàng tương tác với bản đồ lớn hơn. Lưu ý rằng bản đồ nhúng không được hỗ trợ dưới kích thước 200 px thuộc một trong hai phương diện.

Các hạn chế đối với khoá API

Nếu trang web lưu trữ có thẻ meta referrer đang được đặt thành no-referrer hoặc same-origin, thì trình duyệt sẽ không gửi tiêu đề Referer đến Google. Điều này có thể khiến hạn chế về khoá API từ chối các yêu cầu. Để quy tắc hạn chế này hoạt động đúng cách, hãy thêm thuộc tính referrerpolicy vào iframe, như trong ví dụ ở trên, để cho phép rõ ràng gửi tiêu đề Referer đến Google.

Quảng cáo trên bản đồ

API Nhúng của Maps có thể bao gồm cả hoạt động quảng cáo trên bản đồ. Định dạng quảng cáo và nhóm quảng cáo hiển thị trong bất kỳ bản đồ nhất định nào có thể thay đổi mà không có thông báo trước.

Chọn chế độ bản đồ

Bạn có thể chỉ định một trong các chế độ bản đồ sau đây để sử dụng trong URL yêu cầu của mình:

  • place: hiển thị một ghim trên bản đồ tại một địa điểm hoặc địa chỉ cụ thể, chẳng hạn như một địa danh, doanh nghiệp, đối tượng địa lý hoặc thị trấn.
  • view: trả về một bản đồ không có điểm đánh dấu hoặc đường đi.
  • directions: hiển thị đường dẫn giữa hai điểm trở lên được chỉ định trên bản đồ, cũng như khoảng cách và thời gian di chuyển.
  • streetview: hiển thị các chế độ xem toàn cảnh tương tác từ các vị trí được chỉ định.
  • search: hiện kết quả cho một lượt tìm kiếm trên khu vực bản đồ hiển thị.

Chế độ place

URL sau đây sử dụng chế độ bản đồ place để hiển thị một điểm đánh dấu bản đồ tại Tháp Eiffel:

https://www.google.com/maps/embed/v1/place
  ?key=YOUR_API_KEY
  &q=Eiffel+Tower,Paris+France

Bạn có thể sử dụng các tham số sau:

Thông số Loại Nội dung mô tả Giá trị được chấp nhận
q Bắt buộc Xác định vị trí của điểm đánh dấu bản đồ. Tên địa điểm, địa chỉ, mã cộng hoặc mã địa điểm được thoát khỏi URL. API Nhúng của Maps hỗ trợ cả +%20 khi thoát không gian. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc mã cộng "849VCWC8+R9" thành 849VCWC8%2BR9.
center Không bắt buộc Xác định trung tâm của chế độ xem bản đồ. Chấp nhận giá trị vĩ độ và kinh độ được phân tách bằng dấu phẩy; ví dụ: 37.4218,-122.0840.
zoom Không bắt buộc Đặt mức thu phóng ban đầu của bản đồ. Các giá trị thuộc phạm vi từ 0 (toàn thế giới) đến 21 (các toà nhà riêng lẻ). Giới hạn trên có thể thay đổi tuỳ thuộc vào dữ liệu bản đồ có sẵn tại vị trí đã chọn.
maptype Không bắt buộc Xác định loại ô bản đồ cần tải. roadmap (mặc định) hoặc satellite
language Không bắt buộc Xác định ngôn ngữ sử dụng cho các phần tử trên giao diện người dùng và để hiện nhãn trên ô bản đồ. Theo mặc định, khách truy cập sẽ thấy bản đồ bằng ngôn ngữ của họ. Tham số này chỉ được hỗ trợ cho một số thẻ thông tin quốc gia. Nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho tập hợp thẻ thông tin, thì ngôn ngữ mặc định của tập hợp thẻ thông tin đó sẽ được sử dụng.
region Không bắt buộc Xác định các biên giới và nhãn thích hợp để hiển thị, dựa trên sự nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng một thẻ phụ vùng gồm 2 ký tự (không phải số) liên kết với ccTLD (miền cấp cao nhất) quen thuộc với ccTLD (miền cấp cao nhất) gồm 2 giá trị. Xem Thông tin chi tiết về phạm vi áp dụng của Nền tảng Google Maps để biết các khu vực được hỗ trợ.

Chế độ view

Ví dụ sau đây sử dụng chế độ view và tham số maptype không bắt buộc để hiển thị chế độ xem vệ tinh của bản đồ:

https://www.google.com/maps/embed/v1/view
  ?key=YOUR_API_KEY
  &center=-33.8569,151.2152
  &zoom=18
  &maptype=satellite

Bạn có thể sử dụng các tham số sau:

Thông số Loại Nội dung mô tả Giá trị được chấp nhận
center Bắt buộc Xác định trung tâm của chế độ xem bản đồ. Chấp nhận giá trị vĩ độ và kinh độ được phân tách bằng dấu phẩy; ví dụ: 37.4218,-122.0840.
zoom Không bắt buộc Đặt mức thu phóng ban đầu của bản đồ. Các giá trị thuộc phạm vi từ 0 (toàn thế giới) đến 21 (các toà nhà riêng lẻ). Giới hạn trên có thể thay đổi tuỳ thuộc vào dữ liệu bản đồ có sẵn tại vị trí đã chọn.
maptype Không bắt buộc Xác định loại ô bản đồ cần tải. roadmap (mặc định) hoặc satellite
language Không bắt buộc Xác định ngôn ngữ sử dụng cho các phần tử trên giao diện người dùng và để hiện nhãn trên ô bản đồ. Theo mặc định, khách truy cập sẽ thấy bản đồ bằng ngôn ngữ của họ. Tham số này chỉ được hỗ trợ cho một số thẻ thông tin quốc gia. Nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho tập hợp thẻ thông tin, thì ngôn ngữ mặc định của tập hợp thẻ thông tin đó sẽ được sử dụng.
region Không bắt buộc Xác định các biên giới và nhãn thích hợp để hiển thị, dựa trên sự nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng một thẻ phụ vùng gồm 2 ký tự (không phải số) liên kết với ccTLD (miền cấp cao nhất) quen thuộc với ccTLD (miền cấp cao nhất) gồm 2 giá trị. Xem Thông tin chi tiết về phạm vi áp dụng của Nền tảng Google Maps để biết các khu vực được hỗ trợ.

Chế độ directions

Ví dụ sau đây sử dụng chế độ directions để hiển thị đường đi giữa Oslow và Telemark, Na Uy, khoảng cách và thời gian di chuyển để tránh trạm thu phí và đường cao tốc.

https://www.google.com/maps/embed/v1/directions
  ?key=YOUR_API_KEY
  &origin=Oslo+Norway
  &destination=Telemark+Norway
  &avoid=tolls|highways

Bạn có thể sử dụng các tham số sau:

Thông số Loại Nội dung mô tả Giá trị được chấp nhận
origin Bắt buộc Xác định điểm xuất phát để hiện chỉ đường từ đó. Tên địa điểm, địa chỉ, mã cộng, vĩ độ/kinh độ của URL hoặc mã địa điểm. API Nhúng của Maps hỗ trợ cả +%20 khi thoát không gian. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc mã cộng "849VCWC8+R9" thành 849VCWC8%2BR9.
destination Bắt buộc Xác định điểm cuối của chỉ đường. Tên địa điểm, địa chỉ, mã cộng, vĩ độ/kinh độ của URL hoặc mã địa điểm. API Nhúng của Maps hỗ trợ cả +%20 khi thoát không gian. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc mã cộng "849VCWC8+R9" thành 849VCWC8%2BR9.
waypoints Không bắt buộc Chỉ định một hoặc nhiều vị trí trung gian để định tuyến đường đi giữa điểm khởi hành và điểm đến. Tên địa điểm, địa chỉ hoặc mã địa điểm. Bạn có thể chỉ định nhiều điểm tham chiếu bằng cách sử dụng ký tự gạch đứng (|) để đặt các vị trí riêng biệt (ví dụ: Berlin,Germany|Paris,France). Bạn có thể chỉ định tối đa 20 điểm tham chiếu.
mode Không bắt buộc Xác định phương thức di chuyển. Nếu bạn không chỉ định chế độ nào, thì API Nhúng của Maps sẽ hiển thị một hoặc nhiều chế độ phù hợp nhất cho tuyến đường đã chỉ định. driving, walking (ưu tiên đường dành cho người đi bộ và vỉa hè, nếu có), bicycling (các tuyến đường thông qua đường dành cho xe đạp và đường phố ưu tiên nếu có), transit hoặc flying.
avoid Không bắt buộc Chỉ định các tính năng cần tránh khi chỉ đường. Xin lưu ý rằng việc này không loại trừ các tuyến đường chứa(các) đối tượng bị hạn chế; dữ liệu này sẽ làm lệch kết quả đến các tuyến đường có lợi hơn. tolls, ferries và/hoặc highways. Phân tách nhiều giá trị bằng ký tự gạch đứng (ví dụ: avoid=tolls|highways).
units Không bắt buộc Chỉ định phương pháp đo lường, hệ mét hoặc hệ đo lường Anh khi hiển thị khoảng cách trong kết quả. Nếu bạn không chỉ định units, quốc gia origin của truy vấn sẽ xác định các đơn vị sẽ sử dụng. metric hoặc imperial
center Không bắt buộc Xác định trung tâm của chế độ xem bản đồ. Chấp nhận giá trị vĩ độ và kinh độ được phân tách bằng dấu phẩy; ví dụ: 37.4218,-122.0840.
zoom Không bắt buộc Đặt mức thu phóng ban đầu của bản đồ. Các giá trị thuộc phạm vi từ 0 (toàn thế giới) đến 21 (các toà nhà riêng lẻ). Giới hạn trên có thể thay đổi tuỳ thuộc vào dữ liệu bản đồ có sẵn tại vị trí đã chọn.
maptype Không bắt buộc Xác định loại ô bản đồ cần tải. roadmap (mặc định) hoặc satellite
language Không bắt buộc Xác định ngôn ngữ sử dụng cho các phần tử trên giao diện người dùng và để hiện nhãn trên ô bản đồ. Theo mặc định, khách truy cập sẽ thấy bản đồ bằng ngôn ngữ của họ. Tham số này chỉ được hỗ trợ cho một số thẻ thông tin quốc gia. Nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho tập hợp thẻ thông tin, thì ngôn ngữ mặc định của tập hợp thẻ thông tin đó sẽ được sử dụng.
region Không bắt buộc Xác định các biên giới và nhãn thích hợp để hiển thị, dựa trên sự nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng một thẻ phụ vùng gồm 2 ký tự (không phải số) liên kết với ccTLD (miền cấp cao nhất) quen thuộc với ccTLD (miền cấp cao nhất) gồm 2 giá trị. Xem Thông tin chi tiết về phạm vi áp dụng của Nền tảng Google Maps để biết các khu vực được hỗ trợ.

Chế độ streetview

API Nhúng của Maps cho phép bạn hiển thị hình ảnh trong Chế độ xem đường phố dưới dạng ảnh toàn cảnh tương tác từ các vị trí được chỉ định trong toàn bộ khu vực phủ sóng của nó. Bạn cũng có thể sử dụng Ảnh toàn cảnh do người dùng đóng gópbộ sưu tập đặc biệt của Chế độ xem đường phố.

Mỗi ảnh toàn cảnh trong Chế độ xem đường phố đều cung cấp chế độ xem toàn cảnh 360 độ từ một vị trí. Hình ảnh có chế độ xem 360 độ theo chiều ngang (toàn bộ xung quanh) và 180 độ chế độ xem dọc (từ thẳng lên đến thẳng xuống). Chế độ streetview cung cấp trình xem kết xuất ảnh toàn cảnh thu được dưới dạng hình cầu với một máy ảnh ở giữa. Bạn có thể điều khiển máy ảnh để điều khiển mức thu phóng và hướng của máy ảnh.

Xem ảnh toàn cảnh sau đây ở chế độ streetview:

https://www.google.com/maps/embed/v1/streetview
  ?key=YOUR_API_KEY
  &location=46.414382,10.013988
  &heading=210
  &pitch=10
  &fov=35

Một trong các tham số URL sau đây là bắt buộc:

  • location chấp nhận vĩ độ và kinh độ dưới dạng các giá trị được phân tách bằng dấu phẩy (46.414382,10.013988). API sẽ hiển thị ảnh toàn cảnh được chụp gần nhất với vị trí này. Vì hình ảnh trong Chế độ xem đường phố được làm mới định kỳ và mỗi lần chụp ảnh có thể được chụp từ các vị trí hơi khác nhau, nên có khả năng vị trí của bạn sẽ chụp nhanh một ảnh toàn cảnh khác khi hình ảnh được cập nhật.

  • pano là một mã ảnh toàn cảnh cụ thể. Nếu chỉ định pano, bạn cũng có thể chỉ định location. location sẽ chỉ được sử dụng nếu API không thể tìm thấy mã ảnh toàn cảnh.

Các tham số URL sau đây là không bắt buộc:

Thông số Loại Nội dung mô tả Giá trị được chấp nhận
heading Không bắt buộc Cho biết hướng la bàn của máy ảnh theo độ theo chiều kim đồng hồ tính từ Bắc. Giá trị tính theo độ từ -180° đến 360°
pitch Không bắt buộc chỉ định góc, lên hoặc xuống, của máy ảnh. Giá trị dương sẽ nghiêng camera lên trên, còn giá trị âm sẽ nghiêng camera xuống. Cao độ mặc định là 0° được đặt dựa trên vị trí của máy ảnh khi chụp ảnh. Do đó, cao độ 0° thường là chiều ngang, nhưng không phải lúc nào cũng vậy. Ví dụ: hình ảnh chụp trên một ngọn đồi có thể sẽ có độ cao mặc định không nằm ngang. Giá trị tính theo độ từ -90° đến 90°
fov Không bắt buộc xác định trường nhìn ngang của hình ảnh. Trường này mặc định là 90°. Khi xử lý khung nhìn có kích thước cố định, trường nhìn có thể được coi là mức thu phóng, với số nhỏ hơn cho biết mức thu phóng cao hơn. Giá trị tính theo độ, trong khoảng từ 10° đến 100°
center Không bắt buộc Xác định trung tâm của chế độ xem bản đồ. Chấp nhận giá trị vĩ độ và kinh độ được phân tách bằng dấu phẩy; ví dụ: 37.4218,-122.0840.
zoom Không bắt buộc Đặt mức thu phóng ban đầu của bản đồ. Các giá trị thuộc phạm vi từ 0 (toàn thế giới) đến 21 (các toà nhà riêng lẻ). Giới hạn trên có thể thay đổi tuỳ thuộc vào dữ liệu bản đồ có sẵn tại vị trí đã chọn.
maptype Không bắt buộc Xác định loại ô bản đồ cần tải. roadmap (mặc định) hoặc satellite
language Không bắt buộc Xác định ngôn ngữ sử dụng cho các phần tử trên giao diện người dùng và để hiện nhãn trên ô bản đồ. Theo mặc định, khách truy cập sẽ thấy bản đồ bằng ngôn ngữ của họ. Tham số này chỉ được hỗ trợ cho một số thẻ thông tin quốc gia. Nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho tập hợp thẻ thông tin, thì ngôn ngữ mặc định của tập hợp thẻ thông tin đó sẽ được sử dụng.
region Không bắt buộc Xác định các biên giới và nhãn thích hợp để hiển thị, dựa trên sự nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng một thẻ phụ vùng gồm 2 ký tự (không phải số) liên kết với ccTLD (miền cấp cao nhất) quen thuộc với ccTLD (miền cấp cao nhất) gồm 2 giá trị. Xem Thông tin chi tiết về phạm vi áp dụng của Nền tảng Google Maps để biết các khu vực được hỗ trợ.

Chế độ search

Chế độ Search hiển thị kết quả cho một tìm kiếm trong khu vực bản đồ hiển thị. Bạn nên xác định vị trí cho nội dung tìm kiếm bằng cách đưa vị trí vào cụm từ tìm kiếm (record+stores+in+Seattle) hoặc bằng cách thêm tham số centerzoom để liên kết với nội dung tìm kiếm.

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

Bạn có thể sử dụng các tham số sau:

Thông số Loại Nội dung mô tả Giá trị được chấp nhận
q Bắt buộc Xác định cụm từ tìm kiếm. Tệp này có thể bao gồm một giới hạn về địa lý, chẳng hạn như in+Seattle hoặc near+98033.
center Không bắt buộc Xác định trung tâm của chế độ xem bản đồ. Chấp nhận giá trị vĩ độ và kinh độ được phân tách bằng dấu phẩy; ví dụ: 37.4218,-122.0840.
zoom Không bắt buộc Đặt mức thu phóng ban đầu của bản đồ. Các giá trị thuộc phạm vi từ 0 (toàn thế giới) đến 21 (các toà nhà riêng lẻ). Giới hạn trên có thể thay đổi tuỳ thuộc vào dữ liệu bản đồ có sẵn tại vị trí đã chọn.
maptype Không bắt buộc Xác định loại ô bản đồ cần tải. roadmap (mặc định) hoặc satellite
language Không bắt buộc Xác định ngôn ngữ sử dụng cho các phần tử trên giao diện người dùng và để hiện nhãn trên ô bản đồ. Theo mặc định, khách truy cập sẽ thấy bản đồ bằng ngôn ngữ của họ. Tham số này chỉ được hỗ trợ cho một số thẻ thông tin quốc gia. Nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho tập hợp thẻ thông tin, thì ngôn ngữ mặc định của tập hợp thẻ thông tin đó sẽ được sử dụng.
region Không bắt buộc Xác định các biên giới và nhãn thích hợp để hiển thị, dựa trên sự nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng một thẻ phụ vùng gồm 2 ký tự (không phải số) liên kết với ccTLD (miền cấp cao nhất) quen thuộc với ccTLD (miền cấp cao nhất) gồm 2 giá trị. Xem Thông tin chi tiết về phạm vi áp dụng của Nền tảng Google Maps để biết các khu vực được hỗ trợ.

Thông số ID địa điểm

API Nhúng của Maps hỗ trợ việc sử dụng mã địa điểm thay vì cung cấp tên hoặc địa chỉ địa điểm. Mã địa điểm là cách ổn định để xác định duy nhất một địa điểm. Để biết thêm thông tin, hãy xem tài liệu về API Google Địa điểm.

API Nhúng của Maps chấp nhận mã địa điểm cho các tham số URL sau:

  • q
  • origin
  • destination
  • waypoints

Để sử dụng mã địa điểm, trước tiên, bạn phải thêm tiền tố place_id:. Mã sau đây chỉ định Toà thị chính New York làm nguồn gốc cho một yêu cầu chỉ đường: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius đặt một bán kính (tính bằng mét) để tìm kiếm một ảnh toàn cảnh, nằm ở giữa vĩ độ và kinh độ đã cho. Giá trị hợp lệ là số nguyên không âm. Giá trị mặc định là 50.

  • source giới hạn số lượt tìm kiếm trong Chế độ xem đường phố ở các nguồn đã chọn. Các giá trị hợp lệ là:

    • default sử dụng các nguồn mặc định cho Chế độ xem đường phố; các lượt tìm kiếm không bị giới hạn ở các nguồn cụ thể.
    • outdoor giới hạn lượt tìm kiếm ở các bộ sưu tập ngoài trời. Bộ sưu tập trong nhà không được bao gồm trong kết quả tìm kiếm. Xin lưu ý rằng ảnh toàn cảnh ngoài trời có thể không tồn tại đối với vị trí được chỉ định. Ngoài ra, xin lưu ý rằng tính năng tìm kiếm chỉ trả về ảnh toàn cảnh khi có thể xác định xem ảnh đang ở trong nhà hay ngoài trời. Ví dụ: PhotoSpheres không được trả về vì không xác định được ảnh đang ở trong nhà hay ngoài trời.