Thông báo: Kiểu bản đồ cơ sở mới sắp ra mắt trên Nền tảng Google Maps. Bản cập nhật này về kiểu bản đồ bao gồm bảng màu mặc định mới, ghim hiện đại và các điểm cải tiến về trải nghiệm và khả năng sử dụng bản đồ. Tất cả kiểu bản đồ sẽ được tự động cập nhật vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn sử dụng sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

Lập phiên bản

Nhóm API JavaScript của Maps thường xuyên cập nhật API này để bổ sung các tính năng mới, bản sửa lỗi và điểm cải tiến về hiệu suất. Trang này mô tả các phiên bản API có thể dùng trong ứng dụng của bạn.

Kênh phát hành và số phiên bản

Trong ứng dụng, bạn có thể chỉ định kênh phát hành hoặc số phiên bản:

Kênh hằng tuần được chỉ định bằng v=weekly.
Kênh này được cập nhật một lần mỗi tuần và là kênh mới nhất.
Kênh hằng quý được chỉ định bằng v=quarterly.
Kênh này được cập nhật một lần mỗi quý và là kênh có thể dự đoán được nhất.
Kênh thử nghiệm beta được chỉ định bằng v=beta.
Kênh này dựa trên kênh weekly và được cập nhật một lần mỗi tuần. Thông báo này có một số thay đổi khác đối với hoạt động thử nghiệm và phản hồi sớm.
Kênh alpha được chỉ định bằng v=alpha.
Kênh này dựa trên kênh beta và được cập nhật một lần mỗi tuần. Trong đó có các thử nghiệm để thu thập ý kiến phản hồi của khách hàng về nguyên mẫu. Tệp này chỉ dành cho mục đích phát triển và không được sử dụng trong phiên bản phát hành chính thức.
Số phiên bản được chỉ định bằng v=n.nn.
Bạn có thể chọn v=3.58, v=3.57, v=3.56 hoặc v=3.55.
Số phiên bản được cập nhật một lần mỗi quý (xem phần Bản cập nhật hằng quý).

Nếu không chỉ định rõ kênh hoặc phiên bản, bạn sẽ nhận được kênh hằng tuần theo mặc định. Nếu đã chuyển từ gói cao cấp và không chỉ định rõ ràng kênh hoặc phiên bản, thì bạn sẽ nhận được kênh hằng quý theo mặc định. Nếu chỉ định phiên bản không hợp lệ, bạn sẽ nhận được kênh mặc định.

Chọn kênh phát sóng hằng tuần

Đối với hầu hết các ứng dụng, bạn nên chọn kênh hằng tuần. Đây là phiên bản mới nhất và hiện tại, bao gồm các bản sửa lỗi và điểm cải thiện hiệu suất mới nhất. Bạn có thể chỉ định kênh hằng tuần bằng cách tải API JavaScript cho Maps bằng thẻ tập lệnh sau:

  <script>
    (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
      key: "YOUR_API_KEY",
      v: "weekly",
    });
  </script>

Hiện tại, kênh phát hành hằng tuần đang ở phiên bản 3.58. Phiên bản này được cập nhật hằng tuần với các tính năng mới, bản sửa lỗi và điểm cải thiện về hiệu suất.

Vào giữa tháng 11, kênh phát hành hằng tuần sẽ được cập nhật lên phiên bản 3.59. Tại thời điểm đó, phiên bản mới có thể xoá các tính năng không dùng nữa và/hoặc giới thiệu các tính năng không tương thích ngược.

Chọn kênh hằng quý

Một số ứng dụng có thể hưởng lợi từ số lượng bản cập nhật ít hơn nhưng quy mô lớn hơn, vì nó cho khả năng dự đoán tốt hơn. Những ứng dụng này nên sử dụng kênh hằng quý. Hãy sử dụng phương pháp này nếu bạn muốn các bản sửa lỗi và nội dung cải thiện hiệu suất được phát hành đúng thời hạn dự kiến (xem phần bản cập nhật hằng quý). Bạn có thể chỉ định kênh hằng quý bằng cách tải API JavaScript của Maps bằng thẻ tập lệnh sau:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "quarterly",
  });
  </script>

Hiện tại, kênh hằng quý là phiên bản 3.57. Trong quý này, phiên bản này không nhận được tính năng mới, bản sửa lỗi hoặc điểm cải thiện về hiệu suất. Thỉnh thoảng, chúng tôi có thể đưa các bản sửa lỗi bảo mật vào phiên bản này.

Vào giữa tháng 11, kênh phát hành theo quý sẽ được cập nhật lên phiên bản 3.58. Vào thời điểm đó, phiên bản mới sẽ bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc giới thiệu các tính năng không tương thích ngược từ ba tháng trước.

Vào đầu tháng 11, bạn nên kiểm thử ứng dụng bằng v=3.58.

Chọn kênh thử nghiệm beta

Sử dụng kênh thử nghiệm beta để dùng thử các tính năng và thay đổi mới trong phiên bản beta. Các tính năng beta là tính năng đã hoàn thiện nhưng có thể có một số vấn đề chưa được xử lý (vui lòng sử dụng Công cụ theo dõi lỗi để báo cáo vấn đề và đưa ra ý kiến phản hồi). Kênh beta không thuộc phạm vi của bất kỳ thoả thuận mức độ cung cấp dịch vụ (SLA) hoặc chính sách ngừng sử dụng nào, đồng thời một số thay đổi có thể không tương thích ngược với các bản phát hành trước đó.

Kênh này dựa trên kênh weekly và được cập nhật một lần mỗi tuần.

Bạn có thể chỉ định kênh beta bằng cách tải API JavaScript của Maps bằng thẻ tập lệnh sau:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "beta",
  });
  </script>

Chọn kênh alpha

Sử dụng kênh alpha để dùng thử các tính năng và thay đổi thử nghiệm mới. Vui lòng sử dụng Công cụ theo dõi lỗi để báo cáo vấn đề và đưa ra ý kiến phản hồi. Kênh alpha không thuộc phạm vi của bất kỳ thoả thuận mức độ cung cấp dịch vụ (SLA) hoặc chính sách ngừng sử dụng nào, đồng thời một số thay đổi có thể không tương thích ngược với các bản phát hành trước đó. Tệp này chỉ dành cho mục đích phát triển và không được sử dụng trong phiên bản phát hành chính thức.

Kênh này dựa trên kênh beta và được cập nhật một lần mỗi tuần.

Bạn có thể chỉ định kênh alpha bằng cách tải API JavaScript của Maps bằng thẻ tập lệnh sau:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "alpha",
  });
  </script>

Chọn số phiên bản

Chỉ chỉ định phiên bản theo số nếu bạn thường xuyên kiểm tra và cập nhật ứng dụng của mình. Lý do là các phiên bản được đánh số cuối cùng sẽ bị xoá khi các phiên bản mới được tạo mỗi quý. Bạn có thể chỉ định số phiên bản bằng cách tải API JavaScript của Maps bằng thẻ tập lệnh sau:

  <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: 3.57,
  });
  </script>

Hiện tại, bạn có thể chỉ định v=3.58, v=3.57, v=3.56 hoặc v=3.55.

Phiên bản 3.58 sẽ nhận được thông tin cập nhật hằng tuần về các tính năng mới, bản sửa lỗi và điểm cải tiến về hiệu suất.
Phiên bản 3.57 không nhận được bản cập nhật hằng tuần.
Phiên bản 3.56 không nhận được bản cập nhật hằng tuần.
Phiên bản 3.55 không nhận được bản cập nhật hằng tuần.
Thỉnh thoảng, chúng tôi có thể đưa các bản sửa lỗi bảo mật vào bất kỳ phiên bản nào.
Chúng tôi có thể tạo ra những thay đổi không có khả năng tương thích ngược khi tạo một phiên bản mới.

Sau giữa tháng 11, bạn có thể chỉ định v=3.59, v=3.58, v=3.57 hoặc v=3.56.

Phiên bản 3.59 sẽ nhận được bản cập nhật hằng tuần với các tính năng mới, bản sửa lỗi và cải tiến hiệu suất.
Phiên bản 3.58 sẽ không còn nhận được bản cập nhật hằng tuần nữa.
Phiên bản 3.57 sẽ không còn nhận được bản cập nhật hằng tuần nữa.
Phiên bản 3.56 sẽ không còn nhận được bản cập nhật hằng tuần nữa.
Thỉnh thoảng, chúng tôi có thể đưa các bản sửa lỗi bảo mật vào bất kỳ phiên bản nào.
Phiên bản 3.55 sẽ không được cung cấp nữa. Mọi nỗ lực tải phiên bản này sẽ bị bỏ qua và bạn sẽ nhận được kênh mặc định.

Nếu đang sử dụng v=3.56 hoặc v=3.55, bạn nên nâng cấp lên v=3.58 hoặc v=3.57 trước khi giữa tháng 11. Khi chuyển đổi phiên bản, hãy nhớ rằng các phiên bản mới hơn có thể xoá các tính năng không dùng nữa và/hoặc gây ra sự không tương thích ngược.

Sơ đồ dưới đây cho biết phiên bản nào sẽ có trong mỗi kênh trong năm tới.

Một bản cập nhật ảnh hưởng đến đơn đăng ký của tôi

Khi chúng tôi cập nhật kênh phát hành, việc này có thể ảnh hưởng đến ứng dụng của bạn. Điều này có thể xảy ra do ứng dụng của bạn đang dựa vào các tính năng không được ghi nhận hoặc không còn được dùng nữa, hoặc do lỗi hoặc bản sửa lỗi mà chúng tôi đã đưa ra.

Để khắc phục tạm thời, bạn có thể định cấu hình lại ứng dụng để sử dụng phiên bản cũ.

Mở bảng điều khiển trong công cụ cho nhà phát triển của trình duyệt và xem giá trị của google.maps.version.
Cập nhật thẻ tập lệnh tải API và yêu cầu số phiên bản cũ hơn.
Ví dụ: nếu google.maps.version là "3.58.2", hãy sử dụng v=3.57 trong thẻ tập lệnh.
Giải pháp tạm thời này chỉ hoạt động trong một khoảng thời gian giới hạn.

Khi giải pháp tạm thời có hiệu lực, bạn sẽ có thời gian (thường là 3 đến 6 tháng) để cập nhật ứng dụng của mình. Nhờ đó, ứng dụng không còn sử dụng các tính năng chưa được ghi nhận hoặc không dùng nữa cũng như không còn tài khoản để tìm lỗi hoặc bản sửa lỗi nữa.

Sau đó, bạn nên quay lại thẻ tập lệnh ban đầu để tải API.

Bạn cũng có thể tạo yêu cầu hỗ trợ hoặc báo cáo vấn đề.

Thông tin cập nhật hằng quý

Mỗi quý một lần, nhóm Maps JavaScript API phát hành một phiên bản mới. Việc này diễn ra vào giữa tháng 2, giữa tháng 5, giữa tháng 8 và giữa tháng 11. Bản cập nhật tiếp theo sẽ ra mắt vào giữa tháng 11. Kênh hằng tuần mới sẽ cung cấp phiên bản 3.59 và các kênh khác sẽ được cập nhật vào thời điểm đó.

Thông tin cập nhật hằng tuần về kênh

Kênh hằng tuần hiện trỏ đến phiên bản 3.58.

Vào giữa tháng 11, kênh phát hành hằng tuần sẽ được cập nhật từ phiên bản 3.58 lên phiên bản 3.59. Tại thời điểm này, phiên bản mới sẽ bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc giới thiệu các tính năng không tương thích ngược. Bạn có thể cần phải kiểm thử những thay đổi này khi kênh được cập nhật.

Trong suốt quý này, phiên bản mới sẽ được cập nhật hằng tuần với các tính năng mới, bản sửa lỗi và điểm cải tiến về hiệu suất. Việc này sẽ không xoá các tính năng không dùng nữa và sẽ không gây ra sự không tương thích ngược.

Thông tin cập nhật hằng quý về kênh

Kênh phát hành theo quý hiện trỏ đến phiên bản 3.57.

Vào giữa tháng 11, kênh cập nhật hằng quý sẽ được cập nhật từ phiên bản 3.57 lên phiên bản 3.58. Sau khi cập nhật, phiên bản này sẽ bổ sung các tính năng mới, xoá các tính năng không dùng nữa và/hoặc có các trường hợp không tương thích ngược từ 3 tháng trước. Bạn có thể cần kiểm thử những thay đổi này khi kênh được cập nhật.

Trong suốt quý, phiên bản này sẽ không bao gồm các tính năng mới, bản sửa lỗi hay cải thiện hiệu suất. Việc này sẽ không xoá các tính năng không dùng nữa và sẽ không gây ra sự không tương thích ngược.

Bản cập nhật phiên bản

Vào giữa tháng 11, số phiên bản sẽ được chuyển sang để phù hợp với việc phát hành phiên bản mới.

Phiên bản 3.59

Phiên bản 3.59 mới sẽ được phát hành vào giữa tháng 11. Khi phát hành, phiên bản này sẽ bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc có các tính năng không tương thích ngược so với phiên bản 3.58. Bạn nên kiểm thử ứng dụng khi thay đổi giữa các số phiên bản.

Trong quý này, phiên bản mới sẽ được cập nhật hằng tuần với các tính năng mới, bản sửa lỗi và cải tiến về hiệu suất. Việc này sẽ không xoá các tính năng không dùng nữa và sẽ không gây ra sự không tương thích ngược.

Phiên bản 3.58

Phiên bản này bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc có các tính năng không tương thích ngược so với phiên bản 3.57. Bạn nên kiểm thử ứng dụng khi thay đổi giữa các số phiên bản.

Sau giữa tháng 11, phiên bản này sẽ không cập nhật các tính năng mới, bản sửa lỗi và cải thiện hiệu suất nữa. Thao tác này sẽ không xoá các tính năng không dùng nữa và cũng không gây ra trường hợp không tương thích ngược.

Phiên bản 3.57

Phiên bản này bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc giới thiệu các tính năng không tương thích ngược so với phiên bản 3.56. Bạn nên kiểm thử ứng dụng khi thay đổi giữa các số phiên bản.

Phiên bản này sẽ không còn được cập nhật tính năng mới, bản sửa lỗi hoặc điểm cải thiện hiệu suất. Bản phát hành này sẽ không xoá các tính năng không dùng nữa sau phiên bản này và sẽ không gây ra các lỗi không tương thích ngược mới.

Phiên bản 3.56

Phiên bản này bao gồm các tính năng mới, xoá các tính năng không dùng nữa và/hoặc giới thiệu các tính năng không tương thích ngược so với phiên bản 3.55. Bạn nên kiểm thử ứng dụng khi thay đổi giữa các số phiên bản.

Phiên bản 3.55

Sau giữa tháng 11, phiên bản này sẽ bị xoá và không thể sử dụng được nữa. Mọi nỗ lực tải phiên bản này sẽ bị bỏ qua và bạn sẽ nhận được kênh mặc định.

Hỗ trợ phiên bản

Trong mỗi quý, bạn có thể sử dụng 4 phiên bản. Cả 4 phiên bản này đều được hỗ trợ.

Kiểm tra phiên bản

Để gỡ lỗi, hãy sử dụng thuộc tính google.maps.version để có được phiên bản hiện tại của API JavaScript Maps trong ứng dụng của bạn. Mã mẫu sau đây sẽ ghi phiên bản API vào bảng điều khiển của trình duyệt. (Để biết thêm thông tin về bảng điều khiển trình duyệt, hãy xem hướng dẫn kiểm tra lỗi trong trình duyệt.)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

Tài liệu về các phiên bản API

Hướng dẫn cho nhà phát triển luôn mô tả phiên bản hàng tuần.

Ngoài ra, mỗi phiên bản có một tài liệu tham khảo riêng được duy trì:

Tài liệu tham khảo API Phiên bản 3.58 (kênh hằng tuần)
Tài liệu tham khảo API Phiên bản 3.57 (kênh phát hành theo quý)
Tài liệu tham khảo API Phiên bản 3.56
Tài liệu tham khảo API Phiên bản 3.55
Các phiên bản từ 3.0 đến 3.54 đã bị xoá.