Dịch vụ mã hoá địa lý

Tổng quan

Mã hoá địa lý là quy trình chuyển đổi địa chỉ (chẳng hạn như "1600 Amphitheatre Parkway, Mountain View, CA") thành toạ độ địa lý (chẳng hạn như vĩ độ 37.423021 và kinh độ -122.083739). Bạn có thể dùng toạ độ này để đặt điểm đánh dấu hoặc định vị bản đồ.

Mã hoá địa lý ngược là quy trình chuyển đổi toạ độ địa lý thành địa chỉ mà con người có thể đọc được (xem phần Mã hoá địa lý ngược (Tra cứu địa chỉ)).

Bạn cũng có thể dùng trình mã hoá địa lý để tìm địa chỉ cho một mã địa điểm nhất định.

API Maps JavaScript cung cấp một lớp Bộ mã hoá địa lý để mã hoá địa lý và mã hoá địa lý ngược một cách linh động từ thông tin đầu vào của người dùng. Nếu bạn muốn mã hoá địa lý các địa chỉ tĩnh đã biết, hãy xem Dịch vụ mã hoá địa lý trên web.

Bắt đầu

Trước khi sử dụng dịch vụ Mã hoá địa lý trong Maps JavaScript API, trước tiên, hãy đảm bảo rằng bạn đã bật Geocoding API trong Google Cloud Console, trong cùng một dự án mà bạn thiết lập cho Maps JavaScript API.

Cách xem danh sách các API đã bật:

1. Chuyển đến Bảng điều khiển Google Cloud.
2. Nhấp vào nút Chọn một dự án, sau đó chọn dự án mà bạn đã thiết lập cho Maps JavaScript API rồi nhấp vào Mở.
3. Trong danh sách API trên Trang tổng quan, hãy tìm Geocoding API.
4. Nếu thấy API đó trong danh sách, thì bạn không cần làm gì thêm. Nếu API không có trong danh sách, hãy bật API đó:
   1. Ở đầu trang, hãy chọn BẬT API để hiển thị thẻ Thư viện. Hoặc trên trình đơn bên trái, hãy chọn Thư viện.
   2. Tìm kiếm Geocoding API, sau đó chọn API này trong danh sách kết quả.
   3. Chọn BẬT. Khi quá trình này hoàn tất, Geocoding API sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Giá và chính sách

Giá

Để tìm hiểu về chính sách giá và sử dụng cho dịch vụ Mã hoá địa lý bằng JavaScript, hãy xem phần Mức sử dụng và thanh toán cho API Mã hoá địa lý.

Chính sách

Bạn phải sử dụng dịch vụ Mã hoá địa lý theo Chính sách đối với API Mã hoá địa lý.

Yêu cầu mã hoá địa lý

Việc truy cập vào dịch vụ Mã hoá địa lý là không đồng bộ, vì Google Maps API cần thực hiện một lệnh gọi đến máy chủ bên ngoài. Vì lý do đó, bạn cần truyền một phương thức gọi lại để thực thi khi yêu cầu hoàn tất. Phương thức gọi lại này xử lý(các) kết quả. Xin lưu ý rằng trình mã hoá địa lý có thể trả về nhiều kết quả.

Bạn truy cập vào dịch vụ mã hoá địa lý của API Google Maps trong mã bằng cách sử dụng đối tượng trình tạo google.maps.Geocoder. Phương thức Geocoder.geocode() sẽ bắt đầu một yêu cầu đến dịch vụ mã hoá địa lý, truyền cho dịch vụ đó một đối tượng GeocoderRequest theo nghĩa đen chứa các điều khoản đầu vào và một phương thức gọi lại để thực thi khi nhận được phản hồi.

Giá trị cố định đối tượng GeocoderRequest chứa các trường sau:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Tham số bắt buộc: Bạn phải cung cấp một và chỉ một trong các trường sau:

• address – Địa chỉ mà bạn muốn mã hoá địa lý.
       hoặc
  location – LatLng (hoặc LatLngLiteral) mà bạn muốn lấy địa chỉ gần nhất, dễ đọc. Bộ mã hoá địa lý thực hiện thao tác mã hoá địa lý ngược. Hãy xem phần Địa lý mã hoá ngược để biết thêm thông tin.
       hoặc
  placeId – Mã địa điểm của địa điểm mà bạn muốn lấy địa chỉ gần nhất, dễ đọc. Xem thêm về truy xuất địa chỉ cho mã địa điểm.

Tham số không bắt buộc:

• bounds – LatLngBounds mà trong đó kết quả mã hoá địa lý được ưu tiên nổi bật hơn. Tham số bounds sẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn kết quả từ trình mã hoá địa lý. Xem thêm thông tin về việc điều chỉnh cửa sổ xem bên dưới.
• componentRestrictions – Được dùng để giới hạn kết quả trong một khu vực cụ thể. Xem thêm thông tin về bộ lọc thành phần bên dưới.
• region – Mã khu vực, được chỉ định dưới dạng một mã phụ khu vực Unicode gồm 2 ký tự (không phải là số). Trong hầu hết các trường hợp, những thẻ này liên kết trực tiếp với các giá trị quen thuộc gồm 2 ký tự của ccTLD ("miền cấp cao nhất"). Tham số region sẽ chỉ ảnh hưởng chứ không hoàn toàn hạn chế kết quả từ trình mã hoá địa lý. Xem thêm thông tin về phân bổ mã khu vực bên dưới.
• extraComputations – Giá trị duy nhất được phép cho tham số này là ADDRESS_DESCRIPTORS. Hãy xem các bộ mô tả địa chỉ để biết thêm thông tin chi tiết.
• fulfillOnZeroResults – Thực hiện lời hứa về trạng thái ZERO_RESULT trong phản hồi. Điều này có thể là mong muốn vì ngay cả khi không có kết quả mã hoá địa lý, vẫn có thể có các trường cấp độ phản hồi bổ sung được trả về. Hãy xem phần Đáp ứng khi không có kết quả để biết thêm thông tin chi tiết.

Phản hồi mã hoá địa lý

Dịch vụ Geocoding yêu cầu một phương thức gọi lại để thực thi khi truy xuất kết quả của trình mã hoá địa lý. Lệnh gọi lại này phải truyền 2 tham số để lưu giữ results và mã status theo thứ tự đó.

Kết quả mã hoá địa lý

Đối tượng GeocoderResult biểu thị một kết quả mã hoá địa lý. Một yêu cầu mã hoá địa lý có thể trả về nhiều đối tượng kết quả:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Các trường này được giải thích dưới đây:

• types[] là một mảng cho biết loại địa chỉ của kết quả được trả về. Mảng này chứa một tập hợp gồm không hoặc nhiều thẻ xác định loại đối tượng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" cho biết "Chicago" là một thành phố, đồng thời trả về "political" cho biết đây là một thực thể chính trị. Xem thêm thông tin về các loại địa chỉ và các loại thành phần địa chỉ bên dưới.
• formatted_address là một chuỗi ký tự chứa địa chỉ mà con người đọc được của vị trí này.

  Địa chỉ này thường tương đương với địa chỉ bưu điện. Xin lưu ý rằng một số quốc gia (chẳng hạn như Vương quốc Anh) không cho phép phân phối địa chỉ bưu chính thực do các quy định hạn chế về việc cấp phép.

  Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).

  Không phân tích cú pháp địa chỉ được định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi API bao gồm ngoài trường địa chỉ được định dạng.

• address_components[] là một mảng chứa các thành phần riêng biệt áp dụng cho địa chỉ này.

  Mỗi thành phần địa chỉ thường chứa các trường sau:

  • types[] là một mảng cho biết type của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.
  • long_name là nội dung mô tả hoặc tên đầy đủ của thành phần địa chỉ do Geocoder trả về.
  • short_name là tên văn bản viết tắt của thành phần địa chỉ (nếu có). Ví dụ: thành phần địa chỉ cho tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" bằng cách sử dụng chữ viết tắt gồm 2 chữ cái của bưu điện.

  Xin lưu ý những thông tin sau về mảng address_components[]:

  • Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn formatted_address.
  • Mảng này không nhất thiết phải bao gồm tất cả các thực thể chính trị có chứa địa chỉ, ngoài những thực thể có trong formatted_address. Để truy xuất tất cả các thực thể chính trị có chứa một địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý ngược, truyền vĩ độ/kinh độ của địa chỉ làm tham số cho yêu cầu.
  • Định dạng của phản hồi không được đảm bảo giữ nguyên giữa các yêu cầu. Cụ thể, số lượng address_components thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau này.

  Xem thêm thông tin về các loại địa chỉ và các loại thành phần địa chỉ bên dưới.

• partial_match cho biết trình mã hoá địa lý không trả về kết quả khớp chính xác cho yêu cầu ban đầu, mặc dù trình mã hoá này có thể khớp một phần của địa chỉ được yêu cầu. Bạn nên kiểm tra yêu cầu ban đầu để xem có lỗi chính tả và/hoặc địa chỉ không đầy đủ hay không.

  Trường hợp khớp một phần thường xảy ra đối với những địa chỉ đường không tồn tại trong địa phương mà bạn truyền vào yêu cầu. Kết quả trùng khớp một phần cũng có thể được trả về khi một yêu cầu trùng khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả Henry Street và Henrietta Street. Xin lưu ý rằng nếu một yêu cầu có chứa một thành phần địa chỉ bị sai chính tả, thì dịch vụ mã hoá địa lý có thể đề xuất một địa chỉ thay thế. Những đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một kết quả khớp một phần.

• place_idlà giá trị nhận dạng duy nhất của một địa điểm, có thể dùng với các API khác của Google. Ví dụ: bạn có thể dùng place_id với thư viện Google Places API để nhận thông tin chi tiết về một doanh nghiệp địa phương, chẳng hạn như số điện thoại, giờ mở cửa, bài đánh giá của người dùng và nhiều thông tin khác. Xem thông tin tổng quan về mã địa điểm.
• postcode_localities[] là một mảng biểu thị tất cả các địa phương có trong một mã bưu chính và chỉ xuất hiện khi kết quả là một mã bưu chính chứa nhiều địa phương.

• geometry chứa các thông tin sau:

  • location chứa giá trị vĩ độ,kinh độ được mã hoá địa lý. Xin lưu ý rằng chúng ta trả về vị trí này dưới dạng đối tượng LatLng, chứ không phải dưới dạng chuỗi được định dạng.
  • location_type lưu trữ dữ liệu bổ sung về vị trí được chỉ định. Những giá trị sau đây được hỗ trợ:
    • ROOFTOP cho biết rằng kết quả trả về phản ánh một mã địa lý chính xác.
    • RANGE_INTERPOLATED cho biết kết quả trả về phản ánh một giá trị gần đúng (thường là trên đường) được suy đoán giữa 2 điểm chính xác (chẳng hạn như giao lộ). Kết quả được nội suy thường được trả về khi mã địa lý trên mái nhà không có sẵn cho một địa chỉ đường phố.
    • GEOMETRIC_CENTER cho biết kết quả được trả về là tâm hình học của một kết quả, chẳng hạn như đường nhiều đoạn (ví dụ: đường phố) hoặc đa giác (khu vực).
    • APPROXIMATE cho biết kết quả trả về là kết quả ước chừng.
  
  
  • viewport lưu trữ khung hiển thị được đề xuất cho kết quả được trả về.
  • bounds (tuỳ ý được trả về) lưu trữ LatLngBounds có thể chứa toàn bộ kết quả được trả về. Xin lưu ý rằng các ranh giới này có thể không khớp với khung hiển thị được đề xuất. (Ví dụ: San Francisco bao gồm Quần đảo Farallon. Quần đảo này về mặt kỹ thuật là một phần của thành phố, nhưng không được trả về trong khung hiển thị.)

Geocoder trả về địa chỉ bằng chế độ cài đặt ngôn ngữ ưu tiên của trình duyệt hoặc ngôn ngữ được chỉ định khi tải API JavaScript bằng tham số language. (Để biết thêm thông tin, hãy xem phần Bản địa hoá.)

Loại địa chỉ và loại thành phần địa chỉ

Mảng types[] trong GeocoderResult trong phản hồi cho biết loại địa chỉ. Ví dụ về các loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc thực thể chính trị. Mảng types trong GeocoderAddressComponent cho biết loại của từng phần trong địa chỉ. Ví dụ: số nhà hoặc quốc gia.

Địa chỉ có thể có nhiều loại. Các loại này có thể được coi là "thẻ". Ví dụ: nhiều thành phố được gắn thẻ bằng các loại political và locality.

Các loại sau đây được hỗ trợ và trả về trong cả mảng loại địa chỉ và loại thành phần địa chỉ:

Danh sách trống các loại cho biết không có loại nào đã biết cho thành phần địa chỉ cụ thể (ví dụ: Lieu-dit ở Pháp).

Ngoài những thành phần nêu trên, các thành phần địa chỉ có thể bao gồm các loại dưới đây.

Lưu ý: Danh sách này không đầy đủ và có thể thay đổi.

Ngoài những thành phần trên, các thành phần địa chỉ có thể bao gồm các loại được liệt kê bên dưới.

Mã trạng thái

Mã status có thể trả về một trong các giá trị sau:

• "OK" cho biết không có lỗi nào xảy ra; địa chỉ đã được phân tích cú pháp thành công và ít nhất một mã địa lý đã được trả về.
• "ZERO_RESULTS" cho biết mã địa lý đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu trình mã hoá địa lý được truyền một address không tồn tại.
• "OVER_QUERY_LIMIT" cho biết bạn đã vượt quá hạn mức.
• "REQUEST_DENIED" cho biết yêu cầu của bạn đã bị từ chối. Trang web không được phép sử dụng trình mã hoá địa lý.
• "INVALID_REQUEST" thường cho biết rằng truy vấn (address, components hoặc latlng) bị thiếu.
• "UNKNOWN_ERROR" cho biết không xử lý được yêu cầu do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn thử lại.
• "ERROR" cho biết yêu cầu đã hết thời gian chờ hoặc đã xảy ra sự cố khi kết nối với các máy chủ của Google. Yêu cầu có thể thành công nếu bạn thử lại.

Trong ví dụ này, chúng ta sẽ mã hoá địa lý một địa chỉ và đặt một điểm đánh dấu tại các giá trị vĩ độ và kinh độ được trả về. Xin lưu ý rằng trình xử lý được truyền dưới dạng một hàm ẩn danh theo nghĩa đen.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Xem ví dụ.

Thiên vị khung nhìn

Bạn có thể hướng dẫn Dịch vụ mã hoá địa lý ưu tiên kết quả trong một khung hiển thị nhất định (được biểu thị dưới dạng một hộp giới hạn). Bạn thực hiện việc này bằng cách đặt tham số bounds trong ký tự đối tượng GeocoderRequest để xác định ranh giới của khung hiển thị này. Xin lưu ý rằng việc thiên vị chỉ ưu tiên kết quả trong phạm vi; nếu có kết quả phù hợp hơn nằm ngoài phạm vi này, thì kết quả đó vẫn có thể được đưa vào.

Ví dụ: mã địa lý cho "Winnetka" thường trả về vùng ngoại ô này của Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Tuy nhiên, việc chỉ định một tham số bounds xác định một hộp giới hạn cho Thung lũng San Fernando của Los Angeles sẽ khiến mã địa lý này trả về khu dân cư có tên là "Winnetka" ở vị trí đó:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Thiên vị mã vùng

Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả thiên về một khu vực cụ thể một cách rõ ràng bằng cách sử dụng tham số region. Tham số này nhận mã khu vực, được chỉ định dưới dạng thẻ phụ khu vực Unicode gồm 2 ký tự (không phải là số). Các thẻ này liên kết trực tiếp với các giá trị quen thuộc gồm 2 ký tự của ccTLD ("miền cấp cao nhất"), chẳng hạn như "uk" trong "co.uk". Trong một số trường hợp, thẻ region cũng hỗ trợ mã ISO-3166-1. Đôi khi, mã này khác với giá trị ccTLD (ví dụ: "GB" cho "Vương quốc Anh").

Khi sử dụng tham số region:

• Chỉ định một quốc gia hoặc khu vực. Hệ thống sẽ bỏ qua nhiều giá trị và có thể dẫn đến yêu cầu không thành công.
• Chỉ sử dụng thẻ phụ khu vực gồm 2 ký tự (định dạng Unicode CLDR). Tất cả các đầu vào khác sẽ dẫn đến lỗi.
• Chỉ những quốc gia và khu vực có trong Thông tin chi tiết về phạm vi cung cấp của Google Maps Platform mới được hỗ trợ.

Bạn có thể gửi yêu cầu chuyển đổi địa lý cho mọi miền mà ứng dụng Google Maps chính cung cấp dịch vụ chuyển đổi địa lý. Xin lưu ý rằng việc thiên vị chỉ ưu tiên kết quả cho một miền cụ thể; nếu có kết quả phù hợp hơn bên ngoài miền này, thì kết quả đó vẫn có thể được đưa vào.

Ví dụ: mã địa lý cho "Toledo" trả về kết quả này, vì miền mặc định cho Dịch vụ mã hoá địa lý được đặt thành Hoa Kỳ:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Mã địa lý cho "Toledo" với trường region được đặt thành 'es' (Tây Ban Nha) sẽ trả về thành phố Toledo của Tây Ban Nha:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Lọc thành phần

Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả địa chỉ bị hạn chế trong một khu vực cụ thể bằng cách sử dụng bộ lọc thành phần. Chỉ định bộ lọc trong tham số componentRestrictions. Các giá trị bộ lọc hỗ trợ cùng phương thức sửa lỗi chính tả và so khớp một phần như các yêu cầu mã hoá địa lý khác.

Trình mã hoá địa lý chỉ trả về những kết quả khớp với tất cả các bộ lọc thành phần. Tức là nó đánh giá các thông số kỹ thuật của bộ lọc dưới dạng AND chứ không phải OR.

Bộ lọc thành phần bao gồm một hoặc nhiều mục sau:

• route khớp với tên dài hoặc tên ngắn của một tuyến đường.
• locality khớp với các loại địa phương và tiểu địa phương.
• administrativeArea khớp với tất cả các cấp của khu vực hành chính.
• postalCode khớp với mã bưu chính và tiền tố mã bưu chính.
• country khớp với tên quốc gia hoặc mã quốc gia gồm hai chữ cái theo tiêu chuẩn ISO 3166-1. Lưu ý: API tuân theo tiêu chuẩn ISO để xác định các quốc gia và hoạt động lọc sẽ hiệu quả nhất khi bạn sử dụng mã ISO tương ứng của quốc gia.

Ví dụ sau đây minh hoạ cách sử dụng tham số componentRestrictions để lọc theo country và postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Thực hiện khi không có kết quả

Đối với tính năng mã hoá địa lý ngược, theo mặc định, lời hứa sẽ bị phá vỡ trên status=ZERO_RESULTS. Tuy nhiên, các trường cấp phản hồi bổ sung plus_code và address_descriptor vẫn có thể được điền sẵn trong trường hợp này. Nếu bạn cung cấp giá trị true cho tham số fulfillOnZeroResults, thì tham số này sẽ được điền sẵn trong trường hợp này. Nếu giá trị true được cung cấp cho tham số fulfillOnZeroResults, thì promise sẽ không bị gián đoạn và bạn có thể truy cập vào các trường bổ sung này từ promise nếu có.

Sau đây là ví dụ về hành vi này đối với vĩ độ/kinh độ ở Nam Cực. Mặc dù không có kết quả mã hoá địa lý ngược, nhưng chúng ta vẫn có thể in mã cộng trong lời hứa nếu đặt fulfillOnZeroResults=true.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

Bộ mô tả địa chỉ

Nội dung mô tả địa chỉ bao gồm thông tin bổ sung giúp mô tả một vị trí bằng cách sử dụng địa danh và khu vực. Hãy xem bản minh hoạ về bộ mô tả địa chỉ để khám phá tính năng này.

Bạn có thể bật bộ mô tả địa chỉ bằng cách sử dụng tham số extraComputations. Thêm extra_computations=ADDRESS_DESCRIPTORS vào yêu cầu mã hoá địa lý, yêu cầu mã hoá địa lý ngược hoặc yêu cầu mã hoá địa lý về địa điểm để nhận được nội dung mô tả địa chỉ trong phản hồi của bạn.

Ví dụ về tính năng mã hoá địa lý cho địa điểm

Truy vấn sau đây chứa địa chỉ của một địa điểm ở Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({
  geocoder.geocode({
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Ví dụ về mã hoá địa lý ngược

Truy vấn sau đây chứa giá trị vĩ độ/kinh độ cho một vị trí ở Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

Ví dụ về phần mô tả địa chỉ

Sau đây là ví dụ về address_descriptor.

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Có hai mảng trong mỗi đối tượng address_descriptor: landmarks và areas. Mảng landmarks chứa tối đa 5 kết quả được xếp hạng theo mức độ liên quan bằng cách tính đến khoảng cách đến toạ độ được yêu cầu, mức độ phổ biến của địa danh và khả năng hiển thị của địa danh đó. Mỗi kết quả địa danh đều chứa các giá trị sau:

• place_id là mã địa điểm của kết quả địa danh. Xem thông tin tổng quan về mã địa điểm.
• display_name là tên hiển thị của địa danh và chứa language_code và text.
• straight_line_distance_meters là khoảng cách giữa các điểm (tính bằng mét) giữa toạ độ đầu vào và kết quả địa danh.
• travel_distance_meters là khoảng cách tính bằng mét đã đi bằng mạng lưới đường (bỏ qua các quy định hạn chế về đường) giữa toạ độ đầu vào và kết quả địa danh.
• spatial_relationship là mối quan hệ ước tính giữa toạ độ đầu vào và kết quả địa điểm:
• "NEAR" là mối quan hệ mặc định khi không có mối quan hệ nào sau đây được áp dụng.
• "WITHIN" khi toạ độ đầu vào nằm trong phạm vi của cấu trúc được liên kết với điểm mốc.
• "BESIDE" khi toạ độ đầu vào nằm ngay bên cạnh địa danh hoặc điểm truy cập của địa danh.
• "ACROSS_THE_ROAD" khi toạ độ đầu vào nằm ngay đối diện với địa điểm ở phía bên kia của tuyến đường.
• "DOWN_THE_ROAD" khi toạ độ đầu vào nằm trên cùng tuyến đường với địa điểm, nhưng không phải "BESIDES" hoặc "ACROSS_THE_ROAD".
• "AROUND_THE_CORNER" khi toạ độ đầu vào nằm dọc theo một tuyến đường vuông góc với địa điểm (chỉ được phép rẽ một lần).
• "BEHIND" khi toạ độ đầu vào gần với địa danh về mặt không gian, nhưng lại ở xa điểm tiếp cận của địa danh đó.
• types là Các loại địa điểm của địa danh.

Đối tượng areas chứa tối đa 3 phản hồi và chỉ giới hạn ở những địa điểm đại diện cho các khu vực nhỏ, chẳng hạn như khu dân cư, địa điểm phụ và các khu phức hợp lớn. Những khu vực chứa toạ độ được yêu cầu sẽ xuất hiện đầu tiên và được sắp xếp theo thứ tự từ nhỏ nhất đến lớn nhất. Mỗi kết quả areas đều chứa các giá trị sau:

• place_id là mã địa điểm của kết quả khu vực. Xem thông tin tổng quan về mã địa điểm.
• display_name là tên hiển thị của khu vực và chứa language_code và text.
• containment là mối quan hệ ước tính về khả năng chứa giữa toạ độ đầu vào và kết quả về khu vực:
• "NEAR" là mối quan hệ mặc định khi không có mối quan hệ nào sau đây được áp dụng.
• "WITHIN" khi toạ độ đầu vào gần với tâm của khu vực.
• "OUTSKIRTS" khi toạ độ đầu vào gần với rìa của khu vực.

Mức độ phù hợp của bộ mô tả địa chỉ

Bộ mô tả địa chỉ có trong GA cho Ấn Độ. Việc sử dụng bộ mô tả địa chỉ ở Ấn Độ không mất thêm chi phí và việc sử dụng được bao gồm trong SKU Geocoding (Ấn Độ) Essentials hiện có.

Phản hồi

Tính năng này có ở tất cả các khu vực. Tính năng này đang ở giai đoạn phát hành rộng rãi ở Ấn Độ và ở giai đoạn thử nghiệm trước khi phát hành rộng rãi ở tất cả các khu vực khác. Chúng tôi rất mong nhận được ý kiến phản hồi của bạn:

• Nếu bạn gặp vấn đề chỉ liên quan đến khu vực Ấn Độ, hãy liên hệ với nhóm hỗ trợ.
• Để gửi ý kiến phản hồi về bản phát hành thử nghiệm, hãy gửi email cho chúng tôi theo địa chỉ address-descriptors-feedback@google.com.
• Hãy xem Thông tin chi tiết về phạm vi của bộ mô tả địa chỉ để biết thêm thông tin.

Mã hoá địa lý ngược (Tra cứu địa chỉ)

Thuật ngữ đánh dấu vị trí địa lý thường dùng để chỉ việc chuyển đổi một địa chỉ mà con người có thể đọc được thành một vị trí trên bản đồ. Quá trình thực hiện ngược lại, tức là dịch một vị trí trên bản đồ thành một địa chỉ mà con người có thể đọc được, được gọi là địa lý hoá ngược.

Thay vì cung cấp address dạng văn bản, hãy cung cấp một cặp vĩ độ/kinh độ được phân tách bằng dấu phẩy trong tham số location.

Ví dụ sau đây mã hoá một giá trị vĩ độ/kinh độ và đặt bản đồ ở vị trí đó, hiển thị một cửa sổ thông tin có địa chỉ được định dạng:

let marker;

async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] =
        await Promise.all([
            google.maps.importLibrary(
                'maps'
            ) as Promise<google.maps.MapsLibrary>,
            google.maps.importLibrary(
                'geocoding'
            ) as Promise<google.maps.GeocodingLibrary>,
            google.maps.importLibrary(
                'marker'
            ) as Promise<google.maps.MarkerLibrary>,
        ]);

    // Get the gmp-map element.
    const mapElement = document.querySelector(
        'gmp-map'
    ) as google.maps.MapElement;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng') as HTMLInputElement;

    // Get the submit button.
    const submitButton = document.getElementById('submit') as HTMLElement;

    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });

    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();

    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });

    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}

async function geocodeLatLng(
    geocoder: google.maps.Geocoder,
    map: google.maps.Map,
    infowindow: google.maps.InfoWindow
) {
    const input = (document.getElementById('latlng') as HTMLInputElement).value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };

    geocoder
        .geocode({ location: latlng })
        .then((response) => {
            if (response.results[0]) {
                marker.position = latlng;
                map.setCenter(latlng);
                infowindow.setContent(response.results[0].formatted_address);
                infowindow.open(map, marker);
            } else {
                window.alert('No results found');
            }
        })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}

initMap();
index.ts

let marker;
async function initMap() {
    //  Request the needed libraries.
    const [{ Map, InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('geocoding'),
        google.maps.importLibrary('marker'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');
    // Get the inner map.
    const innerMap = mapElement.innerMap;
    // Get the latlng input box.
    const latLngQuery = document.getElementById('latlng');
    // Get the submit button.
    const submitButton = document.getElementById('submit');
    // Set the cursor to crosshair.
    innerMap.setOptions({
        draggableCursor: 'crosshair',
        zoom: 13,
    });
    // Create a marker for re-use.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });
    const geocoder = new Geocoder();
    const infowindow = new InfoWindow();
    // Add a click event listener to the submit button.
    submitButton.addEventListener('click', () => {
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Add a click event listener to the map.
    innerMap.addListener('click', (event) => {
        latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`;
        geocodeLatLng(geocoder, innerMap, infowindow);
    });
    // Make an initial request upon loading.
    geocodeLatLng(geocoder, innerMap, infowindow);
}
async function geocodeLatLng(geocoder, map, infowindow) {
    const input = document.getElementById('latlng').value;
    const latlngStr = input.split(',', 2);
    const latlng = {
        lat: parseFloat(latlngStr[0]),
        lng: parseFloat(latlngStr[1]),
    };
    geocoder
        .geocode({ location: latlng })
        .then((response) => {
        if (response.results[0]) {
            marker.position = latlng;
            map.setCenter(latlng);
            infowindow.setContent(response.results[0].formatted_address);
            infowindow.open(map, marker);
        }
        else {
            window.alert('No results found');
        }
    })
        .catch((e) => window.alert('Geocoder failed due to: ' + e));
}
initMap();
index.js

Xin lưu ý rằng trong ví dụ trước, chúng ta đã cho thấy kết quả đầu tiên bằng cách chọn results[0]. Trình địa lý hoá ngược thường trả về nhiều kết quả. Địa chỉ được mã hoá địa lý không chỉ là địa chỉ bưu chính mà còn là bất kỳ cách nào để đặt tên cho một vị trí theo địa lý. Ví dụ: khi mã hoá địa lý một điểm ở thành phố Chicago, điểm được mã hoá địa lý đó có thể được gắn nhãn là địa chỉ đường phố, là thành phố (Chicago), là tiểu bang (Illinois) hoặc là quốc gia (Hoa Kỳ). Tất cả đều là địa chỉ của trình mã hoá địa lý. Trình mã hoá địa lý ngược sẽ trả về tất cả các kết quả này.

Trình mã hoá địa lý ngược sẽ so khớp các thực thể chính trị (quốc gia, tỉnh, thành phố và khu dân cư), địa chỉ đường phố và mã bưu chính.

Dưới đây là ví dụ về danh sách địa chỉ mà truy vấn ở trên có thể trả về:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Các địa chỉ được trả về theo thứ tự từ khớp nhất đến ít khớp nhất. Thông thường, địa chỉ càng chính xác thì kết quả càng nổi bật, như trong trường hợp này. Xin lưu ý rằng chúng tôi trả về nhiều loại địa chỉ, từ địa chỉ đường cụ thể nhất đến các thực thể chính trị ít cụ thể hơn, chẳng hạn như khu dân cư, thành phố, quận, tiểu bang, v.v. Nếu muốn so khớp một địa chỉ chung chung hơn, bạn có thể muốn kiểm tra trường results[].types.

Lưu ý: Mã hoá địa lý ngược không phải là một khoa học chính xác. Trình mã hoá địa lý sẽ cố gắng tìm vị trí có thể định địa chỉ gần nhất trong một dung sai nhất định.

Truy xuất địa chỉ cho mã địa điểm

Cung cấp placeId để tìm địa chỉ cho một mã địa điểm nhất định. Mã địa điểm là một giá trị nhận dạng duy nhất có thể dùng với các API khác của Google. Ví dụ: bạn có thể cung cấp placeId do Roads API trả về để lấy địa chỉ cho một điểm được điều chỉnh. Để biết thêm thông tin về mã địa điểm, hãy xem bài tổng quan về mã địa điểm.

Khi bạn cung cấp placeId, yêu cầu không được chứa bất kỳ trường nào sau đây:

• address
• latLng
• location
• componentRestrictions

Ví dụ sau đây chấp nhận một mã địa điểm, tìm địa chỉ tương ứng và đặt bản đồ ở vị trí đó. Thao tác này cũng sẽ mở ra một cửa sổ thông tin cho biết địa chỉ được định dạng của địa điểm có liên quan:

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js