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

Tổng quan

Mã hoá đị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 đ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 địa chỉ mà con người có thể đọc được (xem phần Mã hoá địa lý đảo (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 Geocoder để mã hoá địa lý và mã hoá địa lý ngược 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 lý cho các địa chỉ đã biết, hãy xem bài viết Dịch vụ web mã hoá địa lý.

Bắt đầu

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

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

  1. Truy cập vào Google Cloud Console.
  2. Nhấp vào nút Select a project (Chọn dự án), sau đó chọn chính dự án mà bạn đã thiết lập cho Maps JavaScript API rồi nhấp vào Open (Mở).
  3. Trong danh sách API trên Trang tổng quan, hãy tìm API mã hoá địa lý.
  4. Nếu thấy API 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ẻ Thư viện. Ngoài ra, bạn có thể chọn Library (Thư viện) trên trình đơn bên trái.
    2. Tìm kiếm GeoMã hoá API, sau đó chọn API đó từ danh sách kết quả.
    3. Chọn BẬT. Khi quá trình kết thúc, API mã hoá đị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á

Kể từ ngày 16 tháng 7 năm 2018, gói giá mới trả theo mức dùng đã bắt đầu á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ề giá và mức sử dụng đối với việc sử dụng dịch vụ Mã hoá địa lý JavaScript, hãy xem bài viết Mức sử dụng và thanh toán dành cho API mã hoá địa lý.

Chính sách

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

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

Việc truy cập dịch vụ Mã hoá địa lý là không đồng bộ, do API Google Maps cần thực hiện lệnh gọi đến máy chủ bên ngoài. Do đó, bạn cần truyền một phương thức callback để thực thi sau khi hoàn tất yêu cầu. Phương thức gọi lại này sẽ xử lý(các) kết quả. Xin lưu ý rằng bộ 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ã 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ã hoá địa lý, truyền cho dịch vụ đó một giá trị cố định đối tượng GeocoderRequest chứa các điều khoản đầu vào và phương thức gọi lại để thực thi khi nhận được phản hồi.

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

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

  • bounds — LatLngBounds dùng để làm sai lệch kết quả mã hoá địa lý nổi bật hơn. Tham số bounds sẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn đến kết quả từ bộ mã hoá địa lý. Hãy xem thêm thông tin về xu hướng khung nhìn bên dưới.
  • componentRestrictions – Dùng để giới hạn kết quả về 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 ở bên dưới.
  • region – Mã vùng, được chỉ định dưới dạng thẻ phụ vùng Unicode gồm hai ký tự (không phải 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ị gồm 2 ký tự của ccTLD (miền cấp cao nhất) quen thuộc. Tham số region sẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn đến các kết quả từ bộ mã hoá địa lý. Hãy xem thêm thông tin về xu hướng mã vùng bên dưới.
  • extraComputations – Giá trị duy nhất được phép sử dụng cho tham số này là ADDRESS_DESCRIPTORS. Xem phần mô tả địa chỉ để biết thêm 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ể xảy ra vì ngay cả khi không có kết quả mã hoá địa lý thì vẫn có thể có các trường khác ở cấp phản hồi được trả về. Hãy xem phần Thực hiện khi không có kết quả để biết thêm thông tin chi tiết.

Câu trả lời mã hoá địa lý

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

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

Đối tượng GeocoderResult đại diện cho một kết quả mã hoá đị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 không có hoặc nhiều thẻ xác định loại tính năng được trả về trong kết quả. Ví dụ: một 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 đó là một pháp nhân chính trị. Hãy xem thêm thông tin về loại địa chỉ và các loại thành phần địa chỉ dưới đây.
  • formatted_address là một chuỗi chứa địa chỉ mà con người có thể đọc được của vị trí này.

    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 do những quy định hạn chế về giấy 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ố 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ỉ đã đị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ẻ (có trong phản hồi API) 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 của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.
    • long_name là văn bản mô tả đầy đủ hoặc tên của thành phần địa chỉ do Bộ mã hoá địa lý trả về.
    • short_name là tên viết tắt dạng văn bản cho thành phần địa chỉ (nếu có). Ví dụ: thành phần địa chỉ của tiểu bang Alaska có thể có long_name là "Alaska" và short_name là "AK" khi sử dụng chữ viết tắt của bưu điện gồm 2 chữ cái.

    Hãy lưu ý những thông tin sau đây về mảng address_components[]:

    • Mảng các 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 mọi pháp nhân chính trị chứa địa chỉ, ngoại trừ những pháp nhân có trong formatted_address. Để truy xuất tất cả các thực thể chính trị chứa một địa chỉ cụ thể, bạn nên sử dụng phương thức mã hoá địa lý ngược, truyền vĩ độ/kinh độ của địa chỉ dưới dạng tham số đến yêu cầu.
    • Định dạng của phản hồi không được đảm bảo sẽ giống nhau 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 của 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.

    Hãy xem thêm thông tin về loại địa chỉ và các loại thành phần địa chỉ dưới đây.

  • 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 đị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ỉ chưa hoàn chỉnh.

    Kết quả khớp một phần thường xảy ra đối với các địa chỉ đường phố không tồn tại trong địa phương mà bạn chuyển vào trong yêu cầu. Kết quả khớp một phần cũng có thể được trả về khi một yêu cầu khớp với 2 hoặc nhiều vị trí ở cùng một khu vực. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả trùng khớp một phần cho cả đường Henry và đường Henryetta. Lưu ý rằng nếu 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 Google Places API để 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 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 những thông tin sau:

    • location chứa giá trị kinh độ,vĩ độ đượ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. Các giá trị sau hiện được hỗ trợ:
      • ROOFTOP cho biết kết quả trả về phản ánh một mã địa lý 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) được nội suy giữa hai điểm chính xác (chẳng hạn như các giao lộ). Kết quả nội suy thường được trả về khi không có mã địa lý trên mái nhà cho địa chỉ đường phố.
      • GEOMETRIC_CENTER cho biết kết quả trả về là trung tâm hình học của kết quả, chẳng hạn như một hình nhiều đường (ví dụ: một đường phố) hoặc một đa giác (khu vực).
      • APPROXIMATE cho biết rằng kết quả được trả về là 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 được trả về) lưu trữ LatLngBounds có thể chứa đầy đủ kết quả được trả về. Lưu ý rằng các giới hạn này có thể không khớp với khung nhìn được đề 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 bạn không thể trả về quần đảo này trong khung nhìn.)

Các địa chỉ sẽ được Bộ mã hoá địa lý trả về 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 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 cho biết loại địa chỉ. Mảng types[] cũng có thể được trả về trong một GeocoderAddressComponent để cho biết loại của thành phần địa chỉ cụ thể. Các đị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 coi là thẻ. Ví dụ: nhiều thành phố được gắn thẻ bằng loại political và locality.

Bộ mã hoá địa lý hỗ trợ và trả về các loại sau đây ở 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 một tuyến đường có tên (chẳng hạn như "US 101").
  • intersection biểu thị một giao lộ chính, thường là hai con đường chính.
  • political cho biết một pháp nhân chính trị. Thông thường, loại này biểu thị một đa giác của một số hành chính 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 mà Bộ mã hoá địa lý trả về.
  • administrative_area_level_1 cho biết có pháp nhân dân sự thứ nhất ở cấp thấp hơn cấp quốc gia. Tại Hoa Kỳ, những 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 thể hiện các cấp hành chính này. Trong hầu hết các trường hợp, tên rút nhập Hành chính
  • administrative_area_level_2 cho biết một pháp nhân dân sự cấp hai ở cấp thấp hơn cấp quốc gia. Tại Hoa Kỳ, những cấp hành chính này là các hạt. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_3 cho biết có pháp nhân dân sự cấp thứ ba ở cấp thấp hơn cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.
  • administrative_area_level_4 cho biết có pháp nhân dân sự cấp thứ tư ở cấp thấp hơn cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các 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 ở cấp thấp hơn cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các 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 thấp hơn cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các 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 7 ở cấp thấp hơn cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các 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 thành lập hoặc hợp tác với một thành phố hoặc thị trấn.
  • sublocality cho biết một pháp nhân dân sự cấp cao nhất thuộc một đị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: sublocality_level_1 đến sublocality_level_5. Mỗi cấp quận/huyện là một pháp nhân dân sự. Số lớn hơn biểu thị khu vực địa lý nhỏ hơn.
  • neighborhood biểu thị vùng lân cận được đặt tên
  • premise cho biết một vị trí được đặt tên, thường là một toà nhà hoặc tập hợp các toà nhà cùng tên
  • subpremise cho biết một thực thể bậc nhất bên dưới một vị trí đã đặt tên, thường là một toà nhà đơn lẻ trong tập hợp các toà nhà có cùng tên
  • plus_code cho biết một tham chiếu vị trí được mã hoá, lấy từ vĩ độ và kinh độ. Mã Cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những vị trí không tồn tại chúng (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). Hãy truy cập vào https://plus.codes để biết chi tiết.
  • postal_code cho biết mã bưu chính dùng để giải quyết thư bưu chính trong quốc gia.
  • natural_feature biểu thị một đối tượng tự nhiên nổi bật.
  • airport cho biết một sân bay.
  • park biểu thị một công viên có tên.
  • point_of_interest cho biết một địa điểm yêu thích đã được đặt tên. Thông thường, những "POI" này là các thực thể địa phương nổi bật không dễ dàng phù hợp trong một danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Tháp Eiffel".

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, thành phần địa chỉ có thể bao gồm các loại dưới đây.

Lưu ý: Đây chưa phải là danh sách đầy đủ và có thể thay đổi.

  • floor cho biết tầng của một đị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 lân cận được dùng làm tham chiếu để hỗ trợ việc đi theo chỉ dẫn.
  • point_of_interest cho biết một địa điểm yêu thích đã được đặt tên.
  • parking biểu thị bãi đỗ xe hoặc bãi đỗ 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) dùng cho các đị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.
  • bus_station, train_station và transit_station cho biết vị trí của xe buýt, tàu hoả 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à trả về ít nhất một mã địa lý.
  • "ZERO_RESULTS" cho biết mã địa lý đã được mã hoá 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 thông qua 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 bộ mã hoá địa lý.
  • "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 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 liên hệ với 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 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ý được truyền dưới dạng một 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 biểu thị dưới dạng một hộp giới hạn). Bạn có thể thực hiện việc này bằng cách đặt tham số bounds trong giá trị cố định của đối tượng GeocoderRequest để xác định các 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 kết quả phù hợp hơn nằm ngoài những giới hạn này, thì kết quả đó có thể được đưa vào.

Ví dụ: một mã địa lý cho "Winnetka" thường trả về vùng 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 một hộp giới hạn cho Thung lũng San Fernando ở Los Angeles, kết quả trả về mã địa lý này trả về khu vự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"
}

Xu hướng mã vùng

Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả có xu hướng chỉ định một khu vực cụ thể bằng cách sử dụng tham số region. Tham số này sẽ lấy một mã khu vực, được chỉ định dưới dạng thẻ phụ khu vực Unicode gồm hai ký tự (không phải số). 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 và giá trị gồm hai ký 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 khác với các giá trị ccTLD (ví dụ: "GB" đối với "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ành công.
  • Chỉ sử dụng thẻ phụ vùng có 2 ký tự (định dạng CLDR Unicode). Tất cả dữ liệu đầu vào khác sẽ dẫn đến lỗi.
  • Chỉ những quốc gia và khu vực có tên trong phần Thông tin chi tiết về phạm vi phủ sóng của Nền tảng Google Maps mới được hỗ trợ.

Bạn có thể gửi yêu cầu mã hoá địa lý cho mọi miền mà ứng dụng Google Maps chính cung cấp mã hoá địa lý. Xin lưu ý rằng xu hướng chỉ ưu tiên kết quả cho một miền cụ thể; nếu có nhiều kết quả phù hợp hơn bên ngoài miền này thì chúng 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 là 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ý của "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ể đặt Dịch vụ mã hoá địa lý để trả về kết quả địa chỉ bị hạn chế cho 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ã hoá đị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. Điều này có nghĩa là quy trình đánh giá các thông số của bộ lọc là AND (VÀ), 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 địa phương và loại đị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à bộ lọc 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 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 mã hoá địa lý ngược, theo mặc định, cam kết sẽ bị thực hiện trên status=ZERO_RESULTS. Tuy nhiên, trong trường hợp này, bạn vẫn có thể điền các trường mức phản hồi bổ sung plus_code và address_descriptor. Nếu bạn cung cấp giá trị true cho tham số fulfillOnZeroResults, lời hứa sẽ không bị hỏng và bạn có thể truy cập vào các trường bổ sung này từ lời hứa nếu có.

Sau đây là ví dụ về hành vi này đối với một 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`);
        });
    }

Nội dung mô tả địa chỉ

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

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

Ví dụ về mã hoá địa lý địa điểm

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

function addressDescriptorPlaceIdLookup() {
  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 chứa giá trị vĩ độ/kinh độ của 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ó 2 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 xét đến độ gần với toạ độ được yêu cầu, mức độ phổ biến của mốc và chế độ hiển thị của điểm mốc đó. Mỗi kết quả của mốc chứa các giá trị sau:

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

Đối tượng areas chứa tối đa 3 phản hồi và tự giới hạn ở các địa điểm đại diện cho các khu vực nhỏ, chẳng hạn như vùng lân cận, địa phương và các khu phức hợp lớn. Các khu vực có chứa toạ độ được yêu cầu sẽ được liệt kê trước 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ả về khu vực. Xem tổng quan về mã địa điểm.
  • display_name là tên hiển thị của khu vực, bao gồm language_code và text.
  • containment là mối quan hệ ngăn chặn ước tính giữa toạ độ đầu vào và kết quả theo khu vực:
    • "NEAR" là mối quan hệ mặc định khi không có điều nào sau đây á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 cạnh của khu vực.

Phạm vi áp dụng từ khoá mô tả địa chỉ

Tính năng này chỉ dùng được ở một số quốc gia.

Đây là tính năng Xem trước và chúng tôi rất mong nhận được ý kiến phản hồi của bạn. Vui lòng gửi email cho chúng tôi theo địa chỉ address-descriptors-feedback@google.com.

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

Thuật ngữ mã hoá địa lý thường dùng để chỉ việc dịch 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 đảo 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ý đảo 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.

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í đó, thì cửa sổ thông tin sẽ hiển thị 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ử dùng mẫu

Xin lưu ý rằng trong ví dụ trước, chúng tôi đã hiển thị 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 chính mà còn là cách đặt tên theo vị trí địa lý. Ví dụ: khi mã hoá địa lý một điểm trong 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 (Illinois) hoặc quốc gia (Hoa Kỳ). Tất cả đều là địa chỉ cho bộ mã hoá địa lý. Bộ mã hoá địa lý đảo ngược trả về tất cả các kết quả này.

Bộ mã hoá địa lý đảo ngược khớp với các pháp nhân 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 đị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ừ tốt nhất đến ít trùng khớp nhất. Nói chung, địa chỉ chính xác hơn sẽ là kết quả nổi bật nhấ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 phố cụ thể nhất cho đến các pháp nhân chính trị í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 với một địa chỉ chung chung hơn, bạn nê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. Bộ mã hoá địa lý sẽ cố gắng tìm vị trí có thể định địa chỉ gần nhất trong phạm vi dung sai nhất định.

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

Cung cấp placeId để tìm địa chỉ của 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ỉ của một điểm chụp nhanh. Để biết thêm thông tin về mã địa điểm, hãy xem nội dung 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à căn giữa bản đồ tại vị trí đó. Thao tác này cũng sẽ mở ra một cửa sổ thông tin hiển thị địa chỉ đã được định dạng của địa điểm có liên quan:

TypeScript

// 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

JavaScript

// 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
Xem ví dụ

Thử dùng mẫu