Maps Embed API đặt một bản đồ tương tác hoặc ảnh toàn cảnh trong Chế độ xem đường phố trên một trang web thông qua một yêu cầu HTTP được đặt làm URL src của iframe mà không cần JavaScript. Thư viện này hỗ trợ các chế độ bản đồ place, view, directions, streetview và search.
Maps Embed API: thông tin chính
- Sản phẩm: Maps Embed API
- Còn được gọi là: Google Maps Embed API, Maps Embed
- Danh mục: Maps
- Nền tảng: JavaScript (trình duyệt)
- Chạy trên: Ứng dụng khách (mã ứng dụng hoặc trình duyệt)
- Giai đoạn ra mắt: GA
- Vòng đời: Đang hoạt động
- Tổng quan: Tổng quan về Maps Embed API
- Phạm vi cung cấp theo khu vực: Toàn cầu. Chế độ xem đường phố phụ thuộc vào phạm vi của Chế độ xem đường phố; tham số
regionchấp nhận các khu vực được liệt kê trên trang thông tin chi tiết về phạm vi của Nền tảng Maps. (thông tin chi tiết về phạm vi bảo hiểm)
Maps Embed API: trường hợp sử dụng
Sử dụng Maps Embed API khi:
- Bạn cần có một bản đồ tương tác hoặc ảnh toàn cảnh trong Chế độ xem đường phố trên một trang web chỉ sử dụng iframe HTML, không có JavaScript.
- Bạn cần hiển thị ghim vị trí, chế độ xem bản đồ, đường đi giữa các điểm hoặc kết quả tìm kiếm cho một khu vực trong bản đồ được nhúng.
- Bạn cần một bản đồ nhúng không tính phí theo yêu cầu và không có giới hạn về QPS hoặc số yêu cầu hằng ngày (vẫn cần có khoá API).
Không sử dụng Maps Embed API khi:
- Bạn cần tuỳ chỉnh bản đồ web bằng nội dung và hình ảnh của riêng mình. Thay vào đó, hãy sử dụng Maps JavaScript API.
- Bạn cần mở rộng bản đồ được nhúng bằng các tính năng có lập trình ngoài các tham số URL của iframe. Thay vào đó, hãy sử dụng Maps JavaScript API.
Maps Embed API: thiết lập
- Dịch vụ cần bật:
maps-embed-backend.googleapis.com - Xác thực: Khoá API
- Bắt đầu: Thiết lập Maps Embed API
- Tài liệu tham khảo: Tài liệu tham khảo Maps Embed API
- Giá: Mức sử dụng và thanh toán cho Maps Embed API
Maps Embed API: các lỗi thường gặp
- Vấn đề: Nếu trang lưu trữ đặt thẻ meta
referrerthànhno-referrerhoặcsame-origin, thì trình duyệt sẽ không gửi tiêu đềReferervà khoá API bị hạn chế theo liên kết giới thiệu HTTP có thể từ chối các yêu cầu nhúng. Cách khắc phục: Thêmreferrerpolicy="strict-origin-when-cross-origin"vào iframe để miền của trang web được gửi đến Google. Xem /maps/documentation/embed/embedding-map. - Vấn đề: Bản đồ nhúng không được hỗ trợ nếu có kích thước dưới 200 px (chiều rộng hoặc chiều cao). Cách khắc phục: Đặt
widthvàheightcủa iframe thành ít nhất 200 px. Xem /maps/documentation/embed/embedding-map. - Vấn đề: Mặc dù bạn không mất phí sử dụng, nhưng bản đồ tối màu có hình mờ "chỉ dành cho mục đích phát triển" sẽ xuất hiện nếu bạn chưa bật tính năng thanh toán, phương thức thanh toán không hợp lệ, vượt quá giới hạn hằng ngày do bạn tự đặt ra hoặc yêu cầu thiếu trường referer trong HTTP khi sử dụng khoá bị hạn chế theo trường referer. Cách khắc phục: Bật tính năng thanh toán bằng phương thức thanh toán hợp lệ cho dự án, tăng hoặc xoá mọi hạn mức hằng ngày do bạn tự đặt ra và đảm bảo rằng trang giới thiệu được gửi cho các khoá bị hạn chế theo trang giới thiệu (ví dụ: bằng
referrerpolicy="strict-origin-when-cross-origin"trên iframe). Hãy xem /maps/documentation/embed/error-messages. - Vấn đề: Đối với các yêu cầu không hợp lệ (tham số không hợp lệ hoặc bị thiếu, lỗi khoá API và hạn mức như khoá bị thiếu hoặc không hợp lệ, Maps Embed API chưa được bật hoặc vi phạm quy định hạn chế về khoá), chỉ có mã trạng thái HTTP 4xx được báo cáo trong bảng điều khiển của trình duyệt, chứ không có thông báo mô tả; văn bản lỗi xuất hiện bên trong iframe thay cho bản đồ. Cách khắc phục: Đọc văn bản lỗi trong iframe và mã trạng thái của bảng điều khiển (400 cho lỗi tham số, 401 cho khoá bị thiếu, 403 cho khoá không hợp lệ), sau đó xác nhận rằng các tham số là hợp lệ, khoá là hợp lệ, Maps Embed API đã được bật và các quy định hạn chế về khoá cho phép yêu cầu. Hãy xem /maps/documentation/embed/error-messages.
Những việc bạn có thể làm với Maps Embed API
Hãy xem hướng dẫn được liên kết bên dưới cho từng nhiệm vụ hoặc so sánh giữa các sản phẩm trong Trình khám phá chức năng.