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

Dịch vụ mã hóa địa lý

Lưu ý: Thư viện phía máy chủ

Tổng quan

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

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

Bạn cũng có thể sử dụng bộ mã hóa địa lý để tìm địa chỉ cho một mã địa điểm cụ thể.

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

Bắt đầu

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

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

Truy cập vào Google Cloud Console.
Nhấp vào nút Select a project (Chọn một dự án), sau đó chọn cùng một dự án mà bạn đã thiết lập cho API JavaScript của Maps và nhấp vào Mở.
Trong danh sách API trên Trang tổng quan, hãy tìm Geo encoding API.
Nếu thấy API trong danh sách thì bạn đã đặt xong. Nếu API không được liệt kê, hãy bật API đó:
1. Ở đầu trang, hãy chọn ENABLE API (Bật API) để hiển thị thẻ Library. Ngoài ra, trên trình đơn bên trái, hãy chọn Library (Thư viện).
2. Tìm API mã hóa địa lý, sau đó chọn từ danh sách kết quả.
3. Chọn BẬT. Khi quá trình kết thúc, API mã hóa địa lý sẽ xuất hiện trong danh sách API trên Trang tổng quan.

Giá và chính sách

Giá

Bắt đầu có hiệu lực từ ngày 16 tháng 7 năm 2018, gói thanh toán mới trả tiền sẽ được áp dụng cho Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về các giới hạn mới về việc định giá và sử dụng khi sử dụng dịch vụ Mã hóa địa lý JavaScript, hãy xem phần Sử dụng và thanh toán cho API mã hóa địa lý.

Chính sách

Việc sử dụng dịch vụ Mã hóa địa lý phải tuân theo các chính sách được mô tả trong API mã hóa địa lý.

Yêu cầu mã hóa địa lý

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

Bạn truy cập dịch vụ mã hóa địa lý API Google Maps trong mã của mình thông qua đối tượng hàm khởi 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ã hóa địa lý, truyền cho phương thức đối tượng GeocoderRequest một giá trị cố định chứa các cụm từ đầ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ã hóa địa lý.
hoặc
location — LatLng (hoặc LatLngLiteral) mà bạn muốn lấy địa chỉ gần nhất mà con người có thể đọc được. Bộ mã hóa địa lý thực hiện mã hóa địa lý ngược. Xem phần Mã hoá địa lý 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 tìm địa chỉ gần nhất mà con người có thể đọc được. Xem thêm thông tin về cách truy xuất địa chỉ cho mã địa điểm.

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

bounds – LatLngBounds để phân biệt các kết quả mã hóa địa lý một cách nổi bật hơn. Thông số bounds sẽ chỉ ảnh hưởng, không hạn chế hoàn toàn kết quả từ bộ mã hóa địa lý. Xem thêm thông tin về xu hướng khung nhìn bên dưới.
componentRestrictions – Dùng để hạn chế kết quả ở một khu vực cụ thể. Hãy xem thêm thông tin về tính năng lọc thành phần dưới đây.
region – Mã vùng, được chỉ định dưới dạng được chỉ định dưới dạng một thẻ phụ khu vực Unicode hai ký tự (không phải số). Trong hầu hết các trường hợp, các thẻ này sẽ ánh xạ trực tiếp tới các giá trị gồm hai ký tự quen thuộc ccTLD ("miền cấp cao nhất"). Tham số region sẽ chỉ ảnh hưởng, không hạn chế hoàn toàn, kết quả từ bộ mã hóa địa lý. Xem thêm thông tin về xu hướng mã khu vực dưới đây.

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

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

Kết quả mã hóa địa lý

Đối tượng GeocoderResult đại diện cho một kết quả mã hóa địa lý. 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 bên dưới:

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 các thẻ từ 0 trở lên 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ề "địa phương" cho biết rằng "Chicago" là một thành phố và cũng trả về "chính trị" để cho biết đây là một thực thể chính trị. Hã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.
formatted_address là một chuỗi chứa địa chỉ mà con người có thể đọc được.
Thông thường, địa chỉ này 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 sự do các quy định hạn chế.

Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ theo logic. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số đường phố), "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ỉ đã đị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 loại 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ả đầy đủ hoặc tên của thành phần địa chỉ do Geocoder trả về.
- short_name là tên viết tắt cho 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" sử dụng chữ viết tắt gồm 2 chữ cái.
Hãy lưu ý những thông tin sau đây 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ả 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 quy trình mã hóa địa lý ngược, chuyển vĩ độ/kinh độ của địa chỉ dưới dạng tham số vào yêu cầu.
- Định dạng của phản hồi không được đảm bảo sẽ giữ nguyên giữa các yêu cầu. Cụ thể, số lượng address_components sẽ 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. Có thể thiếu một thành phần cụ thể trong phản hồi sau đó.
Hã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 rằng bộ 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ù bộ mã hoá có thể khớp với một phần của địa chỉ đã yêu cầu. Bạn nên kiểm tra yêu cầu ban đầu để tìm lỗi chính tả và/hoặc địa chỉ không đầy đủ.

Kết quả trùng khớp một phần thường xảy ra nhất đối với các địa chỉ đường phố không tồn tại trong phạm vi địa phương mà bạn chuyển trong 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 khớp với hai hoặc nhiều vị trí ở 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. Lưu ý rằng nếu một yêu cầu bao gồm thành phần địa chỉ sai chính tả, thì dịch vụ mã hoá địa lý có thể đề xuất một địa chỉ thay thế. Các đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là khớp một phần.
place_id là giá trị nhận dạng duy nhất của một địa điểm. Bạn có thể sử dụng giá trị này với các API khác của Google. Ví dụ: bạn có thể sử dụng place_id với thư viện API Google Địa điểm để xem 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 ngôn ngữ có trong 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 ngôn ngữ.
geometry chứa các thông tin sau:
- location chứa vĩ độ, giá trị kinh độ, và vị trí được mã hóa đị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ạng chuỗi đã định dạng.
- location_type lưu trữ dữ liệu bổ sung về vị trí đã chỉ định. Hiện có các giá trị sau:
  - 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ị xấp xỉ (thường là trên đường) được nội suy giữa hai điểm chính xác (chẳng hạn như nút giao). Kết quả nội suy thường được trả về khi địa chỉ đường phố không có mã địa lý trên mái nhà.
  - GEOMETRIC_CENTER cho biết kết quả được trả về là trung tâm hình học của một kết quả như đa giác (ví dụ: đường phố) hoặc đa giác (khu vực).
  - APPROXIMATE cho biết rằng kết quả trả về là kết quả gần đúng.
- viewport lưu trữ khung nhìn đề xuất cho kết quả trả về.
- bounds (không bắt buộc trả về) lưu trữ LatLngBounds có thể chứa đầy đủ kết quả trả về. Lưu ý rằng các giới hạn này có thể không khớp với chế độ xem đề xuất. (Ví dụ: San Francisco bao gồm Quần đảo Faarallon, là một phần của thành phố nhưng sẽ không được trả về trong khung nhìn).

Các địa chỉ này sẽ được Geocoder trả về bằng cách sử dụng tuỳ chọn 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 JavaScript API 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 chỉ ra loại địa chỉ. Mảng types[] cũng có thể được trả về trong GeocoderAddressComponent để cho biết loại thành phần địa chỉ cụ thể. Địa chỉ do bộ mã hóa địa lý trả về có thể có nhiều loại; loại có thể được xem là thẻ. Ví dụ: nhiều thành phố được gắn thẻ loại political và locality.

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

street_address cho biết địa chỉ đường phố chính xác.
route biểu thị tuyến đường có tên (chẳng hạn như "US 101").
intersection cho biết giao lộ chính, thường là hai đường chính.
political biểu thị một thực thể chính trị. Thông thường, loại này cho biết một hình đa giác của một số chính quyền dân sự.
country cho biết pháp nhân chính trị quốc gia và thường là loại đơn đặt hàng cao nhất được Geocoder trả về.
administrative_area_level_1 cho biết một thực thể dân sự bậc nhất dưới cấp quốc gia. Ở Hoa Kỳ, các cấp hành chính này là các tiểu bang. Không phải quốc gia nào cũng có những cấp hành chính này. Trong hầu hết các trường hợp, tên ngắn của admin_area_level_1 sẽ phù hợp chặt chẽ với phân mục ISO 3166-2 và các danh sách được lưu hành rộng rãi khác; tuy nhiên, điều này không được đảm bảo vì các kết quả mã hóa địa lý của chúng tôi dựa trên nhiều loại tín hiệu và dữ liệu vị trí.
administrative_area_level_2 biểu thị một pháp nhân dân sự cấp hai dưới cấp quốc gia. Ở Hoa Kỳ, các cấp hành chính này là hạt. Không phải quốc gia nào cũng có những cấp hành chính này.
administrative_area_level_3 cho biết một pháp nhân dân sự cấp ba trong cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
administrative_area_level_4 cho biết một pháp nhân dân sự cấp 4 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
administrative_area_level_5 cho biết một pháp nhân dân sự cấp 5 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
administrative_area_level_6 cho biết một pháp nhân dân sự cấp 6 dưới cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
administrative_area_level_7 cho biết một pháp nhân dân sự cấp bảy trong cấp quốc gia. Loại này cho biết một bộ phận dân sự nhỏ. Không phải quốc gia nào cũng có những cấp hành chính này.
colloquial_area cho biết một tên thay thế thường dùng cho thực thể.
locality cho biết một pháp nhân thành phố hoặc thị trấn hợp nhất.
sublocality cho biết một thực thể dân sự bậc nhất thuộc địa phương. Đối với một số vị trí, bạn có thể nhận được một trong các loại bổ sung sau: sublocality_level_1 đến sublocality_level_5. Mỗi cấp hạt là một pháp nhân dân sự. Số lớn hơn cho biết khu vực địa lý nhỏ hơn.
neighborhood cho biết vùng lân cận đã đặt tên
premise cho biết vị trí được đặt tên, thường là một tòa nhà hoặc tập hợp các tòa nhà có tên chung
subpremise cho biết một thực thể bậc nhất bên dưới một vị trí có tên, thường là một toà nhà đơn nhất trong tập hợp các toà nhà có tên thường gọi
plus_code cho biết tham chiếu vị trí đã mã hoá, được lấy từ vĩ độ và kinh độ. Bạn có thể sử dụng mã cộng để thay thế cho địa chỉ đường phố ở các địa điểm không tồn tại (nơi các tòa nhà không được đánh số hoặc đường phố không được đặt tên). Hãy xem https://plus.codes để biết thông tin chi tiết.
postal_code cho biết mã bưu chính được dùng để gửi thư trong quốc gia.
natural_feature cho biết đối tượng địa lý tự nhiên nổi bật.
airport cho biết sân bay.
park cho biết một công viên được đặt tên.
point_of_interest biểu thị một địa điểm ưa thích đã đặt tên. Thông thường, các "POI" này là các thực thể địa phương nổi bật không dễ dàng phù hợp với danh mục khác, chẳng hạn như "Tòa nhà Empire State" hoặc "Eiffel Tower".

Danh sách loại trống cho biết không có loại dữ liệu đã biết nào cho thành phần địa chỉ cụ thể, chẳng hạn như Lieu-dit ở Pháp.

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

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

floor cho biết số tầng của địa chỉ tòa nhà.
establishment thường biểu thị một địa điểm chưa được phân loại.
landmark cho biết một địa điểm lân cận được dùng làm tệp đối chiếu để hỗ trợ việc di chuyển.
point_of_interest biểu thị một địa điểm ưa thích đã đặt tên.
parking cho biết một bãi đỗ xe hoặc một công trình đỗ xe.
post_box cho biết một hộp thư cụ thể.
postal_town cho biết một nhóm các khu vực địa lý, chẳng hạn như locality và sublocality, được dùng cho địa chỉ gửi thư ở một số quốc gia.
room biểu thị phòng có địa chỉ tòa nhà.
street_number cho biết số nhà chính xác trên phố.
bus_station, train_station và transit_station cho biết vị trí của trạm xe buýt, xe lửa hoặc trạm phương tiện công cộng.

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 rằng mã địa lý thành công nhưng không trả về kết quả. Điều này có thể xảy ra nếu bộ mã hóa được chuyển 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 rằng yêu cầu của bạn đã bị từ chối. Trang web không được phép sử dụng bộ mã hóa đị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 thể xử lý 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 vấn đề khi liên hệ với máy chủ 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 tôi mã hóa địa lý một địa chỉ và đặt một điểm đánh dấu tại các giá trị kinh độ và vĩ độ được trả về. Xin lưu ý rằng trình xử lý được truyền dưới dạng giá trị cố định của hàm ẩn danh.

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

Xu hướng khung nhìn

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

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

{
  "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 tham số bounds xác định hộp giới hạn cho Thung lũng San Fernando của Los Angeles sẽ dẫn đến mã địa lý này trả về vùng lân cận có tên "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"
}

Xu hướng Mã Vùng

Bạn có thể thiết lập Dịch vụ mã hóa địa lý để trả về kết quả sai lệch đối với một khu vực cụ thể bằng cách sử dụng tham số region. Thông số này sẽ lấy một mã vùng, được chỉ định dưới dạng một thẻ con Unicode gồm hai ký tự (không phải số). Các thẻ này liên kết trực tiếp tới các giá trị gồm 2 ký tự quen thuộc 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ợ các mã ISO-3166-1, đôi khi khác với các giá trị ccTLD (ví dụ: "GB" cho "Vương quốc Anh").

Khi sử dụng tham số region:

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

Có thể gửi yêu cầu mã hóa địa lý cho mỗi miền mà ứng dụng Google Maps chính cung cấp mã hóa địa lý. Xin lưu ý rằng xu hướng chỉ ưu tiên các kết quả cho một miền cụ thể. Nếu miền đó có kết quả liên quan hơn thì có thể bao gồm kết quả liên quan.

Ví dụ: một mã địa lý cho "Toledo" sẽ trả về kết quả này, vì miền mặc định cho Dịch vụ mã hóa đị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ột mã địa lý cho "Toledo" với trường region được đặt là 'es' (Tây Ban Nha) sẽ trả về thành phố 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ã hóa địa lý để trả về kết quả địa chỉ bị hạn chế ở 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 một phương pháp sửa lỗi chính tả và khớp một phần như các yêu cầu mã hoá địa lý khác.

Bộ mã hóa chỉ trả về các kết quả phù hợp với tất cả bộ lọc thành phần. Nghĩa là, phương thức này đánh giá thông số kỹ thuật của bộ lọc là 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 ngắn của tuyến đường.
locality so khớp các loại vị trí và cụm dân cư.
administrativeArea khớp với mọi 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 ISO 3166-1. Lưu ý: API tuân theo tiêu chuẩn ISO để xác định các quốc gia và bộ lọc này sẽ hoạt động hiệu quả nhất khi sử dụng mã ISO tương ứng của quốc gia.

Ví dụ sau minh hoạ việc sử dụng thông 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);
  }
});
}

Đảo ngược mã hóa địa lý (Tra cứu địa chỉ)

Thuật ngữ mã hóa địa lý thường đề cập đến việc chuyển một địa chỉ mà con người có thể đọc được sang một vị trí trên bản đồ. Quá trình thực hiện chuyển đổi ngược, 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à mã hóa địa lý 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.

Lưu ý: Nếu bạn đưa tham số componentRestrictions vào yêu cầu, thì tham số location sẽ bị bỏ qua.

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

TypeScript

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

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

JavaScript

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

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

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]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        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));
}

window.initMap = initMap;index.js

Xem ví dụ

Dùng thử mẫu

JSFiddle.net CodeSandbox.io Google Cloud Shell

Xin lưu ý rằng trong ví dụ trước, chúng ta đã hiển thị kết quả đầu tiên bằng cách chọn results[0]. Bộ mã hoá địa lý 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 điện mà còn là cách để đặt tên cho vị trí. Ví dụ: khi mã hóa địa lý một điểm ở thành phố Chicago, điểm được mã hóa đị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à một quốc gia (Hoa Kỳ). Tất cả đều là địa chỉ của bộ mã hóa địa lý. Mã hóa địa lý ngược trả về tất cả các kết quả này.

Bộ mã hóa địa lý ngược khớp với các thực thể chính trị (quốc gia, tỉnh, thành phố và vùng lân cận), địa chỉ đường phố và mã bưu chính.

Dưới đây là ví dụ về danh sách các đị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"

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

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

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

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

Khi 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 ID địa điểm, tìm địa chỉ tương ứng và căn giữa bản đồ tại vị trí đó. Thao tác này cũng làm hiển thị một cửa sổ thông tin hiển thị địa chỉ đã định dạng của địa điểm có liên quan: