Nhúng bản đồ

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

Tạo URL Maps Embed API

Sau đây là ví dụ về URL tải Maps Embed API:

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

Thay thế:

  • MAP_MODE bằng chế độ bản đồ.
  • YOUR_API_KEY bằng khoá API của bạn. Để biết thêm thông tin, hãy xem phần 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 đồ của bạn.

Thêm URL vào iframe

Để sử dụng Maps Embed API trên trang web, hãy đặt URL mà 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 height và width của iframe, ví dụ:

<iframe
  width="450"
  height="250"
  frameborder="0" style="border:0"
  referrerpolicy="strict-origin-when-cross-origin"
  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 nhất định của bản đồ chuyển sang chế độ toàn màn hình.
  • Thuộc tính frameborder="0" và style="border:0" để xoá đường viền iframe chuẩn xung quanh bản đồ.
  • Thuộc tính referrerpolicy="strict-origin-when-cross-origin" đảm bảo rằng trình duyệt gửi miền của trang web dưới dạng tiêu đề Referer đến Google. Điều này cho phép các quy định hạn chế về khoá API xác thực yêu cầu, đồng thời giữ riêng tư các đường dẫn trang cụ thể của bạn.

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

Thông tin về trang giới thiệu và các quy tắc hạn chế đối với khoá API

Nếu trang web lưu trữ có thẻ meta referrer đượ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 quy tắc hạn chế đối với khoá API từ chối các yêu cầu. Để quy định hạn chế 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 gửi rõ ràng tiêu đề Referer đến Google.

  • strict-origin-when-cross-origin (Nên dùng): Chỉ gửi miền cơ sở của bạn (ví dụ: https://example.com/) đến Google. Việc này giúp giữ riêng tư cho các đường dẫn trang cụ thể của bạn, đồng thời vẫn cho phép các quy tắc hạn chế về khoá API hoạt động.
  • no-referrer-when-downgrade (Cũ): Gửi toàn bộ URL, bao gồm cả đường dẫn trang cụ thể và tham số truy vấn (ví dụ: https://example.com/contact?user=123).

Tìm hiểu thêm về tiêu đề Referrer-Policy.

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

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

  • place: hiển thị ghim bản đồ tại một địa điểm hoặc địa chỉ cụ thể, chẳng hạn như đị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 đi giữa hai hoặc nhiều điểm được chỉ định trên bản đồ, cũng như khoảng cách và thời gian di chuyển.
  • streetview: cho thấy chế độ xem toàn cảnh tương tác từ các vị trí được chỉ định.
  • search: cho thấy kết quả 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ị điểm đánh dấu trên 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:

Tham số Loại 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 trên bản đồ. Tên địa điểm, địa chỉ, Plus Code hoặc Mã địa điểm được thoát URL. Maps Embed API hỗ trợ cả + và %20 khi thoát dấu cách. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc Plus Codes "849VCWC8+R9" thành 849VCWC8%2BR9.
center Không bắt buộc Xác định 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 đồ. Giá trị từ 0 (toàn thế giới) đến 21 (từng toà nhà). 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ữ dùng cho các phần tử trên giao diện người dùng và cho việc hiển thị nhãn trên các ô 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ố ô quốc gia; nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho nhóm ô, thì ngôn ngữ mặc định cho nhóm ô đó sẽ được sử dụng.
region Không bắt buộc Xác định đường biên giới và nhãn phù hợp để hiển thị, dựa trên các yếu tố nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng thẻ phụ vùng unicode gồm hai ký tự (không phải số) liên kết với các giá trị gồm hai ký tự quen thuộc của ccTLD ("miền cấp cao nhất"). Xem Thông tin chi tiết về phạm vi của Google Maps Platform để 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:

Tham số Loại Mô tả Giá trị được chấp nhận
center Bắt buộc Xác định 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 đồ. Giá trị từ 0 (toàn thế giới) đến 21 (từng toà nhà). 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ữ dùng cho các phần tử trên giao diện người dùng và cho việc hiển thị nhãn trên các ô 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ố ô quốc gia; nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho nhóm ô, thì ngôn ngữ mặc định cho nhóm ô đó sẽ được sử dụng.
region Không bắt buộc Xác định đường biên giới và nhãn phù hợp để hiển thị, dựa trên các yếu tố nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng thẻ phụ vùng unicode gồm hai ký tự (không phải số) liên kết với các giá trị gồm hai ký tự quen thuộc của ccTLD ("miền cấp cao nhất"). Xem Thông tin chi tiết về phạm vi của Google Maps Platform để biết các khu vực được hỗ trợ.

Chế độ directions

Ví dụ sau đây sử dụng chế độ directions để hiển thị tuyến đường giữa Oslo và Telemark, Na Uy, khoảng cách và thời gian di chuyển tránh các 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:

Tham số Loại 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 thị đường đi. Tên địa điểm, địa chỉ, Plus Code, toạ độ vĩ độ/kinh độ hoặc Mã địa điểm được thoát URL. Maps Embed API hỗ trợ cả + và %20 khi thoát dấu cách. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc Plus Codes "849VCWC8+R9" thành 849VCWC8%2BR9.
destination Bắt buộc Xác định điểm cuối của đường đi. Tên địa điểm, địa chỉ, Plus Code, toạ độ vĩ độ/kinh độ hoặc Mã địa điểm được thoát URL. Maps Embed API hỗ trợ cả + và %20 khi thoát dấu cách. Ví dụ: chuyển đổi "City Hall, New York, NY" thành City+Hall,New+York,NY hoặc Plus Codes "849VCWC8+R9" thành 849VCWC8%2BR9.
waypoints Không bắt buộc Chỉ định một hoặc nhiều địa điểm trung gian để định tuyến đường đi giữa điểm xuất phát 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 (|) để phân tách các địa điểm (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 phương thức, thì Maps Embed API sẽ hiển thị một hoặc nhiều phương thức phù hợp nhất cho tuyến đường đã chỉ định. driving, walking (ưu tiên đường đi bộ và vỉa hè, nếu có), bicycling (ưu tiên các tuyến đường có đường dành cho xe đạp và đường ưu tiên, nếu có), transit hoặc flying.
avoid Không bắt buộc Chỉ định các đối tượng cần tránh trong đường đi. Xin lưu ý rằng điều này không loại trừ các tuyến đường có(các) tính năng bị hạn chế; mà chỉ ưu tiên kết quả cho các tuyến đường phù hợp 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, thì quốc gia origin của truy vấn sẽ xác định đơn vị cần sử dụng. metric hoặc imperial
center Không bắt buộc Xác định 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 đồ. Giá trị từ 0 (toàn thế giới) đến 21 (từng toà nhà). 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ữ dùng cho các phần tử trên giao diện người dùng và cho việc hiển thị nhãn trên các ô 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ố ô quốc gia; nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho nhóm ô, thì ngôn ngữ mặc định cho nhóm ô đó sẽ được sử dụng.
region Không bắt buộc Xác định đường biên giới và nhãn phù hợp để hiển thị, dựa trên các yếu tố nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng thẻ phụ vùng unicode gồm hai ký tự (không phải số) liên kết với các giá trị gồm hai ký tự quen thuộc của ccTLD ("miền cấp cao nhất"). Xem Thông tin chi tiết về phạm vi của Google Maps Platform để biết các khu vực được hỗ trợ.

Chế độ streetview

Maps Embed API 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 khu vực phủ sóng. Bạn cũng có thể xem Ảnh toàn cảnh 360 độ do người dùng đóng góp và bộ 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ố cung cấp một chế độ xem 360 độ đầy đủ từ một vị trí duy nhất. Hình ảnh có chế độ xem ngang 360 độ (bao quát toàn cảnh) và chế độ xem dọc 180 độ (từ thẳng đứng lên đến thẳng đứng xuống). Chế độ streetview cung cấp một trình xem kết xuất ảnh toàn cảnh thu được dưới dạng hình cầu có camera ở giữa. Bạn có thể thao tác với camera để điều khiển mức thu phóng và hướng của camera.

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

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

Bạn phải sử dụng một trong các tham số URL sau:

  • 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 này hiển thị ảnh toàn cảnh được chụp gần vị trí này nhất. Vì hình ảnh trong Chế độ xem đường phố được làm mới định kỳ và ảnh có thể được chụp từ các vị trí hơi khác nhau mỗi lần, nên có thể vị trí của bạn sẽ chuyển sang một ảnh toàn cảnh khác khi hình ảnh được cập nhật.

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

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

Tham số Loại 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 camera theo độ, theo chiều kim đồng hồ từ hướng Bắc. Giá trị tính bằng độ từ -180° đến 360°
pitch Không bắt buộc chỉ định góc của camera, hướng lên hoặc hướng xuống. Giá trị dương sẽ hướng camera lên trên, còn giá trị âm sẽ hướng camera xuống dưới. Độ dốc mặc định là 0° được đặt dựa trên vị trí của camera khi chụp ảnh. Do đó, độ dốc 0° thường là (nhưng không phải lúc nào cũng) nằm ngang. Ví dụ: một hình ảnh được chụp trên đồi có thể sẽ có độ dốc mặc định không nằm ngang. Giá trị tính bằng độ từ -90° đến 90°
fov Không bắt buộc xác định trường nhìn ngang của hình ảnh. Giá trị 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, trong đó số nhỏ hơn cho biết mức thu phóng cao hơn. Giá trị tính bằng độ, trong khoảng từ 10° đến 100°
center Không bắt buộc Xác định 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 đồ. Giá trị từ 0 (toàn thế giới) đến 21 (từng toà nhà). 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ữ dùng cho các phần tử trên giao diện người dùng và cho việc hiển thị nhãn trên các ô 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ố ô quốc gia; nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho nhóm ô, thì ngôn ngữ mặc định cho nhóm ô đó sẽ được sử dụng.
region Không bắt buộc Xác định đường biên giới và nhãn phù hợp để hiển thị, dựa trên các yếu tố nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng thẻ phụ vùng unicode gồm hai ký tự (không phải số) liên kết với các giá trị gồm hai ký tự quen thuộc của ccTLD ("miền cấp cao nhất"). Xem Thông tin chi tiết về phạm vi của Google Maps Platform để biết các khu vực được hỗ trợ.

Chế độ search

Chế độ Search hiển thị kết quả tìm kiếm trên 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 đưa tham số center và zoom vào để giới hạn 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:

Tham số Loại Mô tả Giá trị được chấp nhận
q Bắt buộc Xác định cụm từ tìm kiếm. Giá trị này có thể bao gồm một quy định hạn chế về địa lý, chẳng hạn như in+Seattle hoặc near+98033.
center Không bắt buộc Xác định 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 đồ. Giá trị từ 0 (toàn thế giới) đến 21 (từng toà nhà). 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ữ dùng cho các phần tử trên giao diện người dùng và cho việc hiển thị nhãn trên các ô 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ố ô quốc gia; nếu ngôn ngữ cụ thể được yêu cầu không được hỗ trợ cho nhóm ô, thì ngôn ngữ mặc định cho nhóm ô đó sẽ được sử dụng.
region Không bắt buộc Xác định đường biên giới và nhãn phù hợp để hiển thị, dựa trên các yếu tố nhạy cảm về địa chính trị. Chấp nhận mã vùng được chỉ định dưới dạng thẻ phụ vùng unicode gồm hai ký tự (không phải số) liên kết với các giá trị gồm hai ký tự quen thuộc của ccTLD ("miền cấp cao nhất"). Xem Thông tin chi tiết về phạm vi của Google Maps Platform để biết các khu vực được hỗ trợ.

Tham số mã địa điểm

Maps Embed API hỗ trợ việc sử dụng mã địa điểm thay vì cung cấp tên hoặc địa chỉ của đị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ề Places API (Mới).

Maps Embed API 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:. Đoạn mã sau đây chỉ định Toà thị chính New York là điểm xuất phát cho một yêu cầu chỉ đường: origin=place_id:ChIJs--MqP1YwokRBwAhjXWIHn8.

  • radius đặt bán kính (tính bằng mét) để tìm ảnh toàn cảnh, lấy tâm là 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 phạm vi tìm kiếm trong Chế độ xem đường phố ở những 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 phạm vi tìm kiếm trong các bộ sưu tập ngoài trời. Bộ sưu tập trong nhà không có 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 cho vị trí được chỉ định. Cũng xin lưu ý rằng kết quả tìm kiếm chỉ trả về ảnh toàn cảnh có thể xác định được là ảnh chụp trong nhà hay ngoài trời. Ví dụ: PhotoSpheres không được trả về vì không xác định được liệu chúng ở trong nhà hay ngoài trời.