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 toạ độ địa lý (như vĩ độ 37,423021 và kinh độ -122,083739) mà bạn có thể sử dụng để đặt các điểm đánh dấu hoặc định vị bản đồ.

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

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

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

Bắt đầu

Trước khi sử dụng dịch vụ Mã hoá địa lý trong API Maps JavaScript, 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 bản đồ.

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

Chuyển đến 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 Maps JavaScript API và nhấp vào Open (Mở).
Trong danh sách API trên Dashboard (Trang tổng quan), hãy tìm Geocodes API.
Nếu bạn thấy API này trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API:
1. Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
2. Tìm API mã hóa địa lý, sau đó chọn API này từ danh sách kết quả.
3. Chọn ENABLE (BẬT). Khi quá trình này kết thúc, API mã hóa địa lý sẽ xuất hiện trong danh sách các API trên Trang tổng quan.

Mức giá và các chính sách

Giá

Kể từ ngày 16 tháng 7 năm 2018, gói giá trả theo mức giá mới sẽ có hiệu lực đối với Maps, Tuyến đường và Địa điểm. Để tìm hiểu thêm về hạn mức sử dụng và giá mới cho việc sử dụng dịch vụ Mã hóa địa lý JavaScript, hãy xem bài viết 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 chính sách được mô tả cho API Mã hóa địa lý.

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

Việc truy cập dịch vụ Mã hoá địa lý không đồng bộ vì API Google Maps cần thực hiện lệnh gọi đến một máy chủ bên ngoài. Vì lý do đó, bạn cần chuyển phương thức lệnh gọi lại để thực thi sau 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ả. Vui lòng lưu ý bộ mã hoá có thể trả về nhiều kết quả.

Bạn truy cập vào dịch vụ mã hoá địa lý API Google Maps trong mã của mình thông qua đối tượng hàm dựng 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 nó một giá trị cố định đối tượng GeocoderRequest 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.

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

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

Các thông 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 mà người dùng có thể đọc được. Bộ mã hóa địa lý thực hiện mã địa lý đảo ngược. Hãy xem phần Mã hoá địa lý đảo 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 mà người dùng có thể đọc được. Xem thêm về cách truy xuất địa chỉ cho mã địa điểm.

Các tham số không bắt buộc:

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

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

Dịch vụ mã hoá đị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ã hoá. 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ý. Một yêu cầu mã hóa đị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 tính năng được trả về trong kết quả. Ví dụ: một mã địa lý được mã hoá 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 rằng đây là một pháp nhân chính trị. Bạn có thể 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 hạn chế 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ỉ 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 Hoa Kỳ).

Không được 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ỉ. Hãy xem danh sách các loại được hỗ trợ.
- long_name là phần mô tả bằng văn bản đầy đủ hoặc tên của thành phần địa chỉ do Trình mã hoá địa lý 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à một short_name là "AK" sử dụng chữ viết tắt gồm 2 chữ cái.
Hãy lưu ý những dữ kiện sau về mảng address_components[]:
- Dãy thành phần địa chỉ có thể chứa nhiều thành phần hơn formatted_address.
- Mảng 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ả thực thể chính trị có chứa địa chỉ cụ thể, bạn nên sử dụng quy trình mã hoá địa lý đảo ngược, chuyển vĩ độ/kinh độ của địa chỉ dưới dạng thông số cho yêu cầu.
- Định dạng của phản hồi không được đảm bảo sẽ vẫn giữ nguyên giữa các yêu cầu. Cụ thể, số lượng address_components sẽ khác nhau tùy 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. Thành phần cụ thể có thể bị thiếu trong phản hồi sau.
Bạn có thể 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 bộ mã hoá dữ liệu đã 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ể so 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 để tìm lỗi chính tả và/hoặc địa chỉ không đầy đủ.

Kết quả 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 bạn chuyển trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi yêu cầu khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, Vương quốc Anh" sẽ trả về kết quả khớp một phần cho cả Phố Henry và Phố Henrietta. Hãy lưu ý rằng nếu một yêu cầu bao gồm 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ế. 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_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ể sử dụng place_id với thư viện API Google Địa điểm để 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 bài viết 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 có chứa nhiều địa phương.
geometry chứa các thông tin sau:
- location chứa vĩ độ,kinh độ được mã hoá địa lý. Xin lưu ý rằng chúng tôi 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í đã chỉ định. Hiện có những giá trị sau:
  - ROOFTOP cho biết rằng kết quả trả về phản ánh một tập dữ liệu chính xác.
  - RANGE_INTERPOLATED cho biết rằng kết quả được trả về phản ánh một giá trị gần đúng (thường là trên một con đường) nội suy giữa hai điểm chính xác (chẳng hạn như giao lộ). Kết quả nội suy thường được trả về khi mã hoá địa lý trên mái nhà không có sẵn cho địa chỉ đường phố.
  - GEOMETRIC_CENTER cho biết kết quả được trả về là tâm hình của một kết quả, chẳng hạn như hình nhiều đường (ví dụ: một con đường) hoặc đa giác (vùng).
  - APPROXIMATE cho biết rằng kết quả trả về là giá trị gần đúng.
- viewport lưu trữ khung nhìn đề xuất cho kết quả được trả về.
- bounds (không bắt buộc trả về) lưu trữ LatLngBounds có thể chứa đầy đủ kết quả được trả về. Lưu ý là các giới hạn này có thể không khớp với khung nhìn đề xuất. (Ví dụ: San Francisco bao gồm Quần đảo Farallon, là một phần về mặt kỹ thuật của thành phố, nhưng không được trả về trong khung nhìn.)

Bộ mã hoá địa lý sẽ trả về các địa chỉ bằng cách sử dụ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 JavaScript API bằng cách sử dụng tham số language. (Để biết thêm thông tin, hãy xem nội dung Bản địa hoá.)

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

Mảng types[] trong GeocoderResult cho biết 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ã hoá địa lý trả về có thể có nhiều loại; các loại này có thể được xem là thẻ. Ví dụ: nhiều thành phố được gắn thẻ loại political và locality.

Bộ mã hoá địa lý hỗ trợ và trả về các loại sau đây 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 cho biết tuyến đường có tên (chẳng hạn như "US 101").
intersection biểu thị giao lộ chính, thường là hai đường chính.
political cho biết một thực thể chính trị. Thông thường, loại này cho biết một đa giác của một khu vực hành chính dân sự.
country cho biết thực thể chính trị quốc gia và thường là loại đơn đặt hàng cao nhất do Geocoder trả về.
administrative_area_level_1 cho biết một thực thể dân sự có thứ tự dưới cấp quốc gia. Ở Hoa Kỳ, các cấp quản trị này là tiểu bang. Không phải quốc gia nào cũng có mức độ hành chính như vậy. Trong hầu hết các trường hợp, tên ngắn admin_area_level_1 sẽ khớp hoàn toàn 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 đảm bảo vì kết quả mã hóa địa lý của chúng tôi dựa trên nhiều tín hiệu và dữ liệu vị trí.
administrative_area_level_2 cho biết 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à các hạt. Không phải quốc gia nào cũng có mức độ hành chính như vậy.
administrative_area_level_3 cho biết một pháp nhân dân sự cấp ba 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_4 cho biết một thực thể dân sự bậc 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 thực thể dân sự bậc 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 thực thể 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 thực thể dân sự bậc bảy 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.
colloquial_area cho biết tên thay thế thường dùng cho thực thể.
locality cho biết một pháp nhân chính trị cấp thành phố hoặc thị trấn.
sublocality cho biết một pháp nhân dân sự có thứ tự bên dưới một địa phương. Đối với một số vị trí, có thể bạn sẽ dùng một trong các loại bổ sung: sublocality_level_1 đến sublocality_level_5. Mỗi cấp dân cư là một pháp nhân dân sự. Số lớn hơn biểu thị mộ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í đã đặt tên, thường là một toà nhà hoặc bộ sưu tập các toà nhà có tên thật
subpremise cho biết một thực thể có thứ tự bên dưới một vị trí được đặt tên, thường là một toà nhà duy nhất trong một tập hợp các toà nhà có tên phổ biến.
plus_code cho biết một tệp tham chiếu vị trí đã mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng mã cộng để thay thế địa chỉ đường phố ở những nơi không có mã (các toà nhà không được đánh số hoặc không được đặt tên). Hãy xem https://plus.codes để biết chi tiết.
postal_code cho biết mã bưu chính dùng để gửi thư trong nước ở quốc gia đó.
natural_feature cho biết một đối tượng địa lý tự nhiên nổi bật.
airport biểu thị một sân bay.
park cho biết một công viên được đặt tên.
point_of_interest cho biết địa điểm yêu 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 một danh mục khác, chẳng hạn như "Xây dựng trạng thái Empire" hoặc "Tháp Eiffel".

Danh sách loại trống cho biết không có loại nào đã biết cho thành phần địa chỉ cụ thể, chẳng hạn như Liu-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 tầng của địa chỉ toà nhà.
establishment thường cho biết một địa điểm chưa được phân loại.
landmark cho biết một địa điểm gần đó được dùng làm tệp đối chiếu để hỗ trợ việc điều hướng.
point_of_interest cho biết địa điểm yêu thích đã đặt tên.
parking cho biết bãi đỗ xe hoặc cấu trúc bãi đỗ xe.
post_box cho biế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 các địa chỉ gửi thư ở một số quốc gia.
room cho biết phòng của một địa chỉ toà nhà.
street_number cho biết số đường chính xác.
bus_station, train_station và transit_station cho biết vị trí của trạm xe buýt, xe lửa hoặc 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 chưa xảy ra lỗi nào; đị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ã hoá đị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 bộ mã hoá địa lý được chuyển vào 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 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ã hoá.
"INVALID_REQUEST" thường cho biết 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 này có thể thành công nếu bạn thử lại.
"ERROR" cho biết rằng yêu cầu đã hết thời gian chờ hoặc có vấn đề khi liên hệ với máy chủ của Google. Yêu cầu này có thể thành công nếu bạn thử lại.

Trong ví dụ này, chúng tôi 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ý sẽ được chuyể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ã hoá địa lý ưu tiên kết quả trong một khung nhìn nhất định (được thể hiện dưới dạng một hộp giới hạn). Bạn thực hiện điều này bằng cách đặt thông số bounds trong giá trị cố định đối tượng GeocoderRequest để xác định các giới hạn của khung nhìn này. Lưu ý rằng xu hướng này chỉ ưu tiên các kết quả trong ranh giới đó; nếu kết quả phù hợp hơn tồn tại ngoài giới hạn này thì chúng có thể được bao gồm.

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

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

Khi sử dụng tham số region:

Chỉ chỉ định một quốc gia hoặc khu vực. Nhiều giá trị bị bỏ qua và có thể dẫn đến yêu cầu không thực hiện được.
Chỉ sử dụng các thẻ con của vùng gồm hai ký tự (định dạng Unicode CLDR). Tất cả các giá trị nhập vào khác sẽ dẫn đến lỗi.
Chỉ các quốc gia và khu vực 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ợ.

Bạn 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ý. Lưu ý rằng xu hướng này chỉ ưu tiên các kết quả cho một miền cụ thể. Nếu kết quả phù hợp hơn tồn tại bên ngoài miền này, thì hệ thống có thể bao gồm các kết quả đó.

Ví dụ: một mã địa lý được mã hoá cho "Toledo" sẽ trả về kết quả này, vì miền mặc định của 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ột mã địa lý mã cho "Toledo" có trường region được đặt thành '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ể thiết lập Dịch vụ mã hóa đị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 thông số componentRestrictions. Các giá trị bộ lọc hỗ trợ cùng một phương pháp sửa chính tả và so khớp một phần như các yêu cầu mã hóa địa lý khác.

Bộ mã hoá địa lý chỉ trả về những kết quả khớp với tất cả bộ lọc thành phần. Tức là trang này đánh giá quy cách bộ lọc là VÀ, không phải HOẶC.

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

route khớp với tên dài hoặc ngắn của một tuyến.
locality trùng khớp với loại địa phương và loại địa phương.
administrativeArea phù hợ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 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);
  }
});
}

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

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

Thay vì cung cấp address 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 sẽ 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ụ

Thử mẫu

Stackblitz.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

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

Bộ mã hoá địa lý đảo 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.

Sau đâ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, như trong trường hợp này. Lưu ý rằng chúng tôi trả về các loại địa chỉ khác nhau, từ địa chỉ đường phố cụ thể nhất đến các pháp nhân ít cụ thể hơn (chẳng hạn như vùng lân cận, thành phố, hạt, tiểu bang, v.v. Nếu muốn so khớp một địa chỉ chung hơn), bạn nên kiểm tra trường results[].types.

Lưu ý: Mã hoá địa lý đảo ngược không phải là khoa học chính xác. Bộ mã hoá địa lý sẽ cố gắng tìm vị trí có thể xác định địa chỉ 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 một placeId để tìm địa chỉ của một địa điểm cụ thể. Mã địa điểm là 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 API Đường trả về để nhận địa chỉ cho 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 bạn cung cấp một placeId, yêu cầu này 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ã đị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 sẽ hiển thị một cửa sổ thông tin hiển thị địa chỉ được định dạng của địa điểm liên quan: