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

Tổng quan

Báo địa lý là quá trình chuyển đổi địa chỉ (chẳng hạn như "1600 Amphitheatre Parkway, Mountain View, CA") thành toạ độ địa lý (chẳng hạn như vĩ độ 37,423021 và kinh độ -122,083739). Bạn có thể sử dụng toạ độ này để đặ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 tọa độ địa lý thành địa chỉ mà con người có thể đọc được (xem phần Mã hoá địa lý ngược (Tra cứu địa chỉ)).

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

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

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 bạn đã bật API Mã hoá địa lý trong Google Cloud Console, trong cùng một dự án mà bạn đã thiết lập cho API Maps JavaScript.

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

  1. Chuyển đến Google Cloud Console.
  2. Nhấp vào nút Chọn dự án, sau đó chọn chính dự án mà bạn đã thiết lập cho API Maps JavaScript rồi nhấp vào Mở.
  3. Trong danh sách API trên Trang tổng quan, hãy tìm Geocoding API (API Mã hoá địa lý).
  4. Nếu thấy API trong danh sách, tức là 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 BẬT API để hiển thị thẻ 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 Geocoding API (API Mã hoá địa lý), sau đó chọn API đó trong danh sách kết quả.
    3. Chọn BẬT. Khi quá trình này hoàn tất, Geocoding API (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, chúng tôi đã áp dụng một gói giá mới theo phương thức trả phí khi sử dụng cho Maps, Routes và Places. Để tìm hiểu thêm về mức giá và hạn mức sử dụng mới khi bạn sử dụng dịch vụ Mã hoá địa lý JavaScript, hãy xem phần Sử dụng và thanh toán 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 vào dịch vụ Mã hoá địa lý 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 truyền một 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ả. Xin lưu ý rằng trình dịch địa lý có thể trả về nhiều kết quả.

Bạn truy cập dịch vụ mã hoá đị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() bắt đầu một yêu cầu đến dịch vụ mã hoá địa lý, truyền cho dịch vụ đó một đối tượng GeocoderRequest 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.

Biểu thức cố định đối tượng GeocoderRequest chứa các trường sau:

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

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

  • address – Địa chỉ mà bạn muốn mã hoá địa lý.
         hoặc
    location — LatLng (hoặc LatLngLiteral) mà bạn muốn lấy địa chỉ gần nhất, mà con người có thể đọc được. Bộ mã hoá địa lý thực hiện mã hoá địa lý ngược. Hãy xem phần Biên dịch đị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 lấy địa chỉ gần nhất, có thể đọc được. Xem thêm về cách truy xuất địa chỉ cho mã địa điểm.

Thông số tuỳ chọn:

  • bounds – LatLngBounds trong đó để thiên vị kết quả mã địa lý một cách nổi bật hơn. Tham số bounds chỉ ảnh hưởng chứ không hoàn toàn hạn chế kết quả của trình định mã địa lý. Xem thêm thông tin về tính năng thiên lệch khung nhìn ở bên dưới.
  • componentRestrictions – Dùng để giới hạn kết quả ở một khu vực cụ thể. Hãy xem thêm thông tin về cách lọc thành phần ở bên dưới.
  • region – Mã vùng, được chỉ định dưới dạng thẻ con 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 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 hoàn toàn hạn chế, kết quả của trình mã hoá địa lý. Hãy xem thêm thông tin về hiệu ứng thiên vị mã theo khu vực ở bên dưới.
  • extraComputations – Giá trị duy nhất được phép cho tham số này là ADDRESS_DESCRIPTORS. Hãy xem chỉ số địa chỉ để biết thêm thông tin chi tiết.
  • fulfillOnZeroResults – Thực hiện lời hứa về trạng thái ZERO_RESULT trong phản hồi. Bạn có thể muốn làm như vậy vì ngay cả khi không có kết quả mã hoá địa lý nào, vẫn có thể có các trường cấp phản hồi bổ sung được trả về. Hãy xem phần Thực hiện đơn hàng khi không có kết quả để biết thêm thông tin chi tiết.

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

Dịch vụ Địa chỉ được mã hoá địa lý yêu cầu một phương thức gọi lại để thực thi khi truy xuất kết quả của trình mã hoá địa lý. Lệnh gọi lại này sẽ truyền hai tham số để lưu giữ 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ả duy nhất của quá trình mã hoá địa lý. Yêu cầu mã địa lý có thể trả về nhiều đối tượng kết quả:

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

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

  • types[] là một mảng cho biết loại địa chỉ của kết quả được trả về. Mảng này chứa một tập hợp gồm 0 hoặc nhiều thẻ xác định loại đối tượng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" (khu vực) cho biết "Chicago" là một thành phố, đồng thời trả về "political" (chính trị) cho biết đây là một thực thể chính trị. Xem thêm thông tin về các loại địa chỉ và 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 được của vị trí này.

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

    Địa chỉ được định dạng được tạo thành một cách hợp lý từ một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang ở 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 của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.
    • long_name là nội dung mô tả văn bản đầy đủ hoặc tên của thành phần địa chỉ do Trình định vị đị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à short_name là "AK" bằng cách sử dụng chữ viết tắt theo mã bưu chính gồm 2 chữ cái.

    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ả các thực thể chính trị 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ị chứa một địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý đảo ngược, truyền vĩ độ/kinh độ của địa chỉ dưới dạng tham số cho 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 thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau.

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

  • partial_match cho biết trình dịch đị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ù có thể khớp một phần của địa chỉ được yêu cầu. Bạn nên kiểm tra yêu cầu ban đầu để xem có lỗi chính tả và/hoặc địa chỉ chưa hoàn chỉnh hay không.

    Kết quả trùng khớp một phần thường xảy ra đối với những địa chỉ đường phố không tồn tại trong địa phương mà bạn truyền vào yêu cầu. Kết quả trùng khớp một phần cũng có thể được trả về khi một yêu cầu khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả đường Henry và Henrietta. Xin lưu ý rằng nếu một yêu cầu có 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ế. Nội dung đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một kết quả trùng 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ể được sử 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 để lấy 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 nội dung tổng quan về mã địa điểm.
  • postcode_localities[] là một mảng biểu thị tất cả địa phương có trong một mã bưu chính và chỉ xuất hiện khi kết quả là một mã bưu chính chứa nhiều địa phương.

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

    • location chứa giá trị vĩ độ,kinh độ được mã hoá địa lý. Xin lưu ý rằng chúng ta trả về vị trí này dưới dạng đối tượng LatLng, chứ không phải dưới dạng chuỗi được định dạng.
    • location_type lưu trữ dữ liệu bổ sung về vị trí được chỉ định. Các giá trị sau đây 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 kết quả 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 sân thượng cho địa chỉ đường phố.
      • GEOMETRIC_CENTER cho biết kết quả trả về là tâm hình học của một kết quả, chẳng hạn như đường đa tuyến (ví dụ: đường phố) hoặc đa giác (khu vực).
      • APPROXIMATE cho biết kết quả trả về là gần đúng.

    • viewport lưu trữ khung nhìn được đề xuất cho kết quả được trả về.
    • bounds (không bắt buộc phải trả về) lưu trữ LatLngBounds có thể chứa đầy đủ kết quả được trả về. Xin 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, về mặt kỹ thuật là một phần của thành phố, nhưng không được trả về trong khung nhìn.)

Địa chỉ sẽ được Trình dịch đị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 JavaScript API bằng thông 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 GeocoderAddressComponent để cho biết loại thành phần địa chỉ cụ thể. Địa chỉ do trình 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.

Các loại sau đây được hỗ trợ và trả về bởi trình định vị địa lý 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 một tuyến đường được đặt tên (chẳng hạn như "US 101").
  • intersection cho biết một giao lộ chính, thường là của 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 số cơ quan 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 thứ tự cao nhất do Trình định vị địa lý trả về.
  • administrative_area_level_1 cho biết một thực thể dân sự cấp một bên dưới cấp quốc gia. Tại Hoa Kỳ, các cấp quản lý này là tiểu bang. Không phải quốc gia nào cũng có các cấp quản lý này. Trong hầu hết các trường hợp, tên ngắn administrative_area_level_1 sẽ khớp gần như hoàn toàn với các tiểu khu ISO 3166-2 và các danh sách khác được lưu hành rộng rãi; tuy nhiên, điều này không được đảm bảo vì kết quả mã hoá đị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 thực thể dân sự cấp hai thấp hơn cấp quốc gia. Tại 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ó các cấp quản lý này.
  • administrative_area_level_3 cho biết một thực thể dân sự cấp ba thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các 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 bốn thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này.
  • administrative_area_level_5 cho biết một thực thể dân sự cấp thứ năm bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này.
  • administrative_area_level_6 cho biết một thực thể dân sự bậc sáu bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các 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 thứ bảy bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có 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 thực thể chính trị của thành phố hoặc thị trấn được hợp nhất.
  • sublocality cho biết một thực thể dân sự cấp một bên dưới 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 địa phương phụ là một thực thể dân sự. Số lớn hơn cho biết khu vực địa lý nhỏ hơn.
  • neighborhood cho biết một khu vực đượ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 một tập hợp các toà nhà có tên chung.
  • subpremise cho biết một thực thể có thể định địa chỉ ở cấp dưới cơ sở, chẳng hạn như căn hộ, phòng hoặc căn hộ.
  • plus_code cho biết một tệp tham chiếu vị trí được mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng plus code thay cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố (những nơi không đánh số nhà hoặc không đặt tên đường). Hãy xem https://plus.codes để biết thông tin chi tiết.
  • postal_code cho biết mã bưu chính dùng để gửi thư qua đường bưu chính trong quốc gia.
  • natural_feature cho biết một đặc điểm tự nhiên nổi bật.
  • airport cho biết một sân bay.
  • park cho biết một công viên có tên.
  • point_of_interest cho biết một điểm yêu thích được đặt tên. Thông thường, "điểm yêu thích" (POI) là những thực thể nổi bật tại địa phương không dễ dàng phù hợp với một danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Tháp Eiffel".

Danh sách loại trống cho biết không có loại nào được 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 trên, thành phần địa chỉ có thể bao gồm các loại dưới đây.

Lưu ý: Danh sách này 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 lân cận được dùng làm tham chiếu để hỗ trợ điều hướng.
  • point_of_interest cho biết một điểm yêu thích được đặt tên.
  • parking cho biết bãi đỗ xe hoặc nhà đỗ xe.
  • post_box cho biết một hộp thư bưu chính 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 cho biết phòng của địa chỉ toà 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 trạm xe buýt, trạm 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 mã địa lý đã được tạo thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu trình mã hoá địa lý được truyền một address không tồn tại.
  • "OVER_QUERY_LIMIT" cho biết bạn đã vượt quá hạn mức.
  • "REQUEST_DENIED" cho biết yêu cầu của bạn đã bị từ chối. Trang web không được phép sử dụng trình mã hoá địa lý.
  • "INVALID_REQUEST" thường cho biết rằng truy vấn (address, components hoặc latlng) bị thiếu.
  • "UNKNOWN_ERROR" cho biết không 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 ta sẽ mã hoá địa lý một địa chỉ và đặ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 cố định ẩ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ụ.

Chế độ thiên lệch 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 hộp giới hạn). Bạn thực hiện việc này bằng cách đặt tham số bounds trong giá trị cố định đối tượng GeocoderRequest để xác định giới hạn của khung nhìn này. Xin lưu ý rằng việc thiên vị chỉ ưu tiên các kết quả nằm trong giới hạn; nếu có kết quả phù hợp hơn nằm ngoài giới hạn này, thì các kết quả đó có thể được đưa vào.

Ví dụ: mã địa lý của "Winnetka" thường trả về khu đô thị 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 ở Los Angeles sẽ khiến mã địa lý này trả về khu vực 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"
}

Chế độ thiên vị mã vùng

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

Khi sử dụng tham số region:

  • Chỉ chỉ định một quốc gia hoặc khu vực. Nhiều giá trị sẽ 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ụ theo khu vực gồm hai ký tự (định dạng Unicode CLDR). Tất cả dữ liệu đầu vào khác sẽ dẫn đến lỗi.
  • Chỉ hỗ trợ những quốc gia và khu vực được liệt kê trong Thông tin chi tiết về phạm vi cung cấp của Nền tảng Google Maps.

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 dịch vụ mã hoá địa lý. Xin lưu ý rằng việc thiên vị chỉ ưu tiên kết quả cho một miền cụ thể; nếu có kết quả phù hợp hơn bên ngoài miền này, thì các kết quả đó có thể được đưa vào.

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

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

Mã địa lý cho "Toledo" với trường region được đặt thành 'es' (Tây Ban Nha) sẽ trả về thành phố 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ế ở 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. Giá trị bộ lọc hỗ trợ các phương thức sửa lỗi chính tả và so khớp một phần giống như các yêu cầu mã hoá địa lý khác.

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

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

  • route khớp với tên dài hoặc ngắn của một tuyến.
  • locality so khớp với các loại địa phương và địa phương phụ.
  • administrativeArea khớp với tất cả cấp độ của khu vực hành chính.
  • postalCode so khớp 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 ISO 3166-1 gồm hai chữ cái. Lưu ý: API tuân theo tiêu chuẩn ISO để xác định quốc gia và tính năng 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 đây minh hoạ cách sử dụng tham số componentRestrictions để lọc theo country và postalCode:

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

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

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

Sau đây là ví dụ về hành vi này đối với vĩ độ/kinh độ ở Nam Cực. Mặc dù không có kết quả mã hoá địa lý đảo ngược, nhưng chúng ta vẫn có thể in mã plus 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ỉ

Thông tin mô tả địa chỉ bao gồm thông tin bổ sung giúp mô tả một vị trí bằng cách sử dụng các địa danh và khu vực. Hãy xem bản minh hoạ về chỉ số 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 việc sử dụng tham số extraComputations. Thêm extra_computations=ADDRESS_DESCRIPTORS vào yêu cầu mã hoá địa lý, yêu cầu mã hoá địa lý ngược hoặc yêu cầu mã hoá địa lý địa điểm để nhận thông tin mô tả địa chỉ trong phản hồi.

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

Truy vấn sau đây 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ề việc mã hoá địa lý ngược

Truy vấn sau đây 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ề chỉ số mô tả địa chỉ

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

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

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

Đối tượng areas chứa tối đa 3 phản hồi và giới hạn ở những nơi đại diện cho các khu vực nhỏ, chẳng hạn như khu dân cư, khu vực phụ và khu phức hợp lớn. Các khu vực chứa toạ độ được yêu cầu được liệt kê trước và được sắp xếp từ nhỏ nhất đến lớn nhất. Mỗi kết quả areas 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 và chứa language_code và text.
  • containment là mối quan hệ chứa ước tính giữa toạ độ đầu vào và kết quả về diện tích:
    • "NEAR" là mối quan hệ mặc định khi không có mối quan hệ nào sau đây được áp dụng.
    • "WITHIN" khi toạ độ đầu vào gần với tâm của khu vực.
    • "OUTSKIRTS" khi toạ độ đầu vào nằm gần mép khu vực.

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

Tính năng này chỉ 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.

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

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

Ví dụ sau đây sẽ mã hoá địa lý một giá trị vĩ độ/kinh độ và đặt bản đồ ở vị trí trung tâm tại vị trí đó, hiển thị một cửa sổ thông tin có đị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

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]. Trình dịch đị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 chính, mà còn là mọi cách để đặt tên theo vị trí địa lý cho một vị trí. 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ố, thành phố (Chicago), tiểu bang (Illinois) hoặc quốc gia (Hoa Kỳ). Tất cả đều là địa chỉ của trình mã hoá địa lý. Trình dịch địa lý đảo ngược sẽ trả về tất cả các kết quả này.

Trình dịch địa lý ngược so khớp các thực thể chính trị (quốc gia, tỉnh, thành phố và khu vực 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"

Địa chỉ được trả về theo thứ tự từ khớp nhất đến ít khớp nhất. Nói chung, địa chỉ càng chính xác thì kết quả càng nổi bật, như trong trường hợp này. Xin lưu ý rằng chúng tôi trả về nhiều loại địa chỉ, từ địa chỉ đường phố cụ thể nhất đến các thực thể chính trị ít cụ thể hơn như khu dân cư, 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ý ngược không phải là một khoa học chính xác. Trình mã hoá địa lý sẽ cố gắng tìm vị trí có thể định địa chỉ gần nhất trong một mức dung sai nhất định.

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

Cung cấp placeId để tìm địa chỉ cho một mã địa điểm nhất định. Mã địa điểm là một giá trị nhận dạng duy nhất có thể được 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 được 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 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 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 cho thấy đị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ử mẫu