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ể 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ý 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.
Maps JavaScript API cung cấp một lớp Bộ mã hoá địa lý để mã hoá địa lý và mã hoá địa lý ngược một cách linh động dựa trên thông tin do người dùng nhập. 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ý. Để so sánh Geocoder với các API khác của Google Maps Platform cho tính năng tìm kiếm tự động hoàn thành, xác minh địa chỉ bưu chính hoặc tra cứu múi giờ, hãy xem bài viết Chọn API địa chỉ hoặc toạ độ phù hợp.
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 Geocoding API trong Google Cloud Console, trong cùng một dự án mà bạn thiết lập cho API JavaScript của Maps.
Cách xem danh sách các API đã bật:
- Chuyển đến Google Cloud Console.
- Nhấp vào nút 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 rồi nhấp vào Mở.
- Trong danh sách API trên Trang tổng quan, hãy tìm Geocoding API.
- 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 đó:
- Ở đầ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.
- Tìm Geocoding API, sau đó chọn API này trong danh sách kết quả.
- Chọn BẬT. Khi quá trình này hoàn tất, Geocoding API sẽ xuất hiện trong danh sách API trên Trang tổng quan.
Nếu bản đồ của bạn không hiển thị hoặc bảng điều khiển của trình duyệt ghi lại lỗi khoá API hoặc lỗi kích hoạt, hãy xem phần Khắc phục sự cố và Thông báo lỗi.
Giá và chính sách
Giá
Để tìm hiểu về chính sách giá và chính sách sử dụng cho dịch vụ Mã hoá địa lý JavaScript, hãy xem phần Mức sử dụng và thanh toán cho API Mã hoá địa lý.
Chính sách
Bạn phải sử dụng dịch vụ Mã hoá địa lý theo Chính sách dành cho Geocoding API.
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ộ, đòi hỏi phải gọi đến một máy chủ bên ngoài. Vì lý do này, phương thức geocode sẽ trả về một lời hứa sẽ giải quyết khi hoàn tất yêu cầu. Sau khi giải quyết xong, bạn có thể sử dụng .then() hoặc await để xử lý phản hồi.
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 bằng cách sử dụng đố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ụ này một đối tượng chữ GeocoderRequest 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.
Đối tượng chữ 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ặcLatLngLiteral) mà bạn muốn lấy địa chỉ gần nhất, 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 Mã hoá địa lý ngược để biết thêm thông tin.
hoặc
placeId— Mã địa điểm của địa điểm mà bạn muốn lấy địa chỉ gần nhất mà con người có thể đọc được. Xem thêm thông tin về cách truy xuất địa chỉ cho mã địa điểm.
Tham số không bắt buộc:
bounds—LatLngBoundsmà bạn muốn ưu tiên kết quả mã hoá địa lý một cách nổi bật hơn. Tham sốboundssẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn kết quả từ bộ mã hoá địa lý. Xem thêm thông tin về thiên vị 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ể. Xem thêm thông tin về bộ lọc thành phần bên dưới.region— Mã khu vực, được chỉ định dưới dạng thẻ phụ khu vực 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 với các giá trị gồm hai ký tự quen thuộc của ccTLD ("tên miền cấp cao nhất"). Tham sốregionsẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn kết quả từ bộ mã hoá địa lý. Xem thêm thông tin về thiên vị mã vùng bên dưới.extraComputations— Giá trị duy nhất được phép cho tham số này làADDRESS_DESCRIPTORS. Hãy xem phần mô tả địa chỉ để biết thêm thông tin chi tiết.fulfillOnZeroResults— Thực hiện lời hứa về trạng thái ZERO_RESULT trong phản hồi. Điều này có thể là mong muốn vì ngay cả khi không có kết quả mã hoá địa lý, vẫn có thể có các trường cấp phản hồi bổ sung được trả về. Hãy xem phần Thực hiện khi không có kết quả để biết thêm thông tin chi tiết.
Phản hồi về việc mã hoá địa lý
Dịch vụ 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 bộ mã hoá địa lý. Lệnh gọi lại này phải truyền hai tham số để 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ả 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 dưới đây:
types[]là một mảng cho biết loại địa chỉ của kết quả được trả về. Mảng này chứa một tập hợp gồm không hoặc nhiều thẻ xác định loại đối tượng được trả về trong kết quả. Ví dụ: mã địa lý của "Chicago" trả về "locality" (địa phương) 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_addresslà 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 các quy định hạn chế về việc cấp phép.
Địa chỉ được định dạng bao gồm một hoặc nhiều thành phần địa chỉ. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "8th Avenue" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).
Đừng phân tích cú pháp địa chỉ được định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ mà phản hồi của 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ỉ. Thành phần địa chỉ có thể có một mảng loại trống khi không có loại nào đã biết cho thành phần địa chỉ đó. API có thể thêm các giá trị loại mới nếu cần. Để biết thêm thông tin, hãy xem phần Loại địa chỉ và loại thành phần địa chỉ.long_namelà tên hoặc nội dung mô tả đầy đủ bằng văn bản của thành phần địa chỉ do Bộ mã hoá địa lý trả về.short_namelà tên viết tắt bằng văn bản của thành phần địa chỉ (nếu có). Ví dụ: một thành phần địa chỉ cho tiểu bang Alaska có thể cólong_namelà "Alaska" vàshort_namelà "AK" bằng cách sử dụng chữ viết tắt gồm 2 chữ cái của bưu điện.
Hãy lưu ý những thông tin sau về mảng
address_components[]:- Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn
formatted_address. - Mảng này không nhất thiết phải bao gồm tất cả các thực thể chính trị 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ý 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 giữ nguyên giữa các yêu cầu. Cụ thể, số lượng
address_componentssẽ thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian cho cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong phản hồi sau này.
Xem thêm thông tin về các loại địa chỉ và loại thành phần địa chỉ bên dưới.
-
partial_matchcho biết 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ù có thể khớp một phần đị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 đầy đủ hay không.Kết quả 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 chuyển trong yêu cầu. Kết quả trùng khớp một phần cũng có thể được trả về khi một yêu cầu khớp với hai hoặc nhiều vị trí trong cùng một địa phương. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả Henry Street và Henrietta Street. Xin lưu ý rằng nếu một yêu cầu có chứa thành phần địa chỉ bị viết 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à kết quả trùng khớp một phần.
place_idlà giá trị nhận dạng riêng biệt của một địa điểm, có thể dùng được với các API khác của Google. Ví dụ: bạn có thể sử dụngplace_idcùng 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.v. 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.geometrychứa các thông tin sau:locationchứa giá trị 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ượngLatLng, chứ không phải dưới dạng chuỗi được định dạng.location_typelưu trữ dữ liệu bổ sung về vị trí được chỉ định. Những giá trị sau đây được hỗ trợ:ROOFTOPcho biết kết quả được trả về phản ánh một mã địa lý chính xác.RANGE_INTERPOLATEDcho biết kết quả được trả về phản ánh giá trị gần đúng (thường là trên đường) được 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ã địa lý trên mái nhà không có sẵn cho địa chỉ đường phố.GEOMETRIC_CENTERcho biết kết quả được trả về là tâm hình học của một kết quả, chẳng hạn như hình nhiều đường (ví dụ: đường phố) hoặc đa giác (khu vực).APPROXIMATEcho biết kết quả trả về là gần đúng.
viewportlưu trữ khung nhìn được đề xuất cho kết quả trả về.bounds(trả về không bắt buộc) lưu trữLatLngBoundscó 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ỉ đượ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 JavaScript API bằng tham số language. (Để biết thêm thông tin, hãy xem phần
Bản địa hoá.)
Loại địa chỉ và loại thành phần địa chỉ
Mảng types[] trong GeocoderResult trong phản hồi cho biết loại địa chỉ. Ví dụ về các loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc pháp nhân chính trị. Mảng types trong GeocoderAddressComponent cho biết loại của từng phần trong địa chỉ. Ví dụ: số nhà hoặc quốc gia.
Địa chỉ có thể có nhiều loại. Các loại này có thể được coi là "thẻ".
Ví dụ: nhiều thành phố được gắn thẻ bằng các loại political và locality.
Các loại sau đây được hỗ trợ và trả về trong cả mảng loại địa chỉ và mảng loại thành phần địa chỉ:
| Loại địa chỉ | Mô tả |
|---|---|
street_address |
Địa chỉ đường phố chính xác. |
route |
Tuyến đường có tên (chẳng hạn như "US 101"). |
intersection |
Một giao lộ lớn, thường là của hai con đường chính. |
political |
Một pháp nhân chính trị. Thông thường, loại này cho biết đa giác của một số cơ quan quản lý dân sự. |
country |
Thực thể chính trị quốc gia và thường là loại thứ tự cao nhất mà Bộ mã hoá địa lý trả về. |
administrative_area_level_1 |
Khu vực hành chính cấp một dưới cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là tiểu bang. Chỉ một số quốc gia có các cấp hành chính 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 đúng với các phân khu ISO 3166-2 và các danh sách được lưu hành rộng rãi khác; tuy nhiên, điều này không được đảm bảo vì 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 |
Khu vực hành chính cấp hai dưới cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là quận. Chỉ một số quốc gia có các cấp hành chính này. |
administrative_area_level_3 |
Khu vực hành chính cấp ba dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này. |
administrative_area_level_4 |
Khu vực hành chính cấp bốn dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này. |
administrative_area_level_5 |
Khu vực hành chính cấp năm dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này. |
administrative_area_level_6 |
Khu vực hành chính cấp sáu dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này. |
administrative_area_level_7 |
Khu vực hành chính cấp bảy dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này. |
colloquial_area |
Tên thay thế thường dùng cho pháp nhân. |
locality |
Một pháp nhân chính trị của thành phố hoặc thị trấn đã đăng ký thành lập. |
sublocality |
Một khu vực hành chính cấp một dưới cấp địa phương. Một số địa điểm 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ố càng lớn thì khu vực địa lý càng nhỏ. |
neighborhood |
Một khu vực lân cận có tên. |
premise |
Một vị trí có tên, thường là một toà nhà hoặc một nhóm toà nhà có tên chung. |
subpremise |
Một thực thể có địa chỉ bên dưới cấp cơ sở, chẳng hạn như căn hộ, đơn vị hoặc phòng. |
plus_code |
Mã tham chiếu vị trí được mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng Plus Codes để thay thế cho địa chỉ đường phố ở những nơi không có địa chỉ (nơi các toà nhà không được đánh số hoặc đường phố không có tên). Hãy xem https://plus.codes để biết thông tin chi tiết. |
postal_code |
Mã bưu chính dùng để gửi thư bưu chính trong quốc gia. |
natural_feature |
Một đối tượng tự nhiên nổi bật. |
airport |
Sân bay. |
park |
Công viên có tên. |
point_of_interest |
Một địa điểm yêu thích có tên. Thông thường, những "địa điểm yêu thích" này là các 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 đã biết cho thành phần địa chỉ cụ thể (ví dụ: Lieu-dit ở Pháp).
Ngoài các thành phần nêu 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.
Ngoài các thành phần nêu trên, thành phần địa chỉ có thể bao gồm các loại được liệt kê dưới đây.
| Loại thành phần địa chỉ | Mô tả |
|---|---|
floor |
Tầng của địa chỉ toà nhà. |
establishment |
Thường là một địa điểm chưa được phân loại. |
landmark |
Một địa điểm lân cận được dùng làm điểm tham chiếu để hỗ trợ việc đi theo chỉ dẫn. |
point_of_interest |
Một địa điểm yêu thích có tên. |
parking |
Bãi đỗ xe hoặc nhà đỗ xe. |
post_box |
Một hộp thư bưu điện cụ thể. |
postal_town |
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 |
Phòng của địa chỉ toà nhà. |
street_number |
Số nhà chính xác. |
bus_station, train_station và transit_station |
Vị trí của trạm xe buýt, tàu hoả 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 không có lỗi nào xảy ra; địa chỉ đã được phân tích cú pháp thành công và ít nhất một mã địa lý đã được trả về."ZERO_RESULTS"cho biết rằng mã 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 truyền mộtaddresskhô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 rằng truy vấn (address,componentshoặclatlng) bị thiếu."UNKNOWN_ERROR"cho biết rằng không thể xử lý yêu cầu do lỗi phía 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.
Ví dụ về mã hoá địa lý
Ví dụ sau đây minh hoạ cách 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ề. Kết quả mã hoá địa lý được xử lý bằng một lời hứa. Nhấp vào vị trí bất kỳ trên bản đồ để mã hoá địa lý địa chỉ tại vị trí đó.
TypeScript
async function geocode(request: google.maps.GeocoderRequest) { clear(); const { LatLng } = await google.maps.importLibrary('core'); try { const response = await geocoder.geocode(request); const { results } = response; innerMap.setCenter(results[0].geometry.location); marker.position = new LatLng(results[0].geometry.location); mapElement.append(marker); responseDiv.style.display = 'block'; responsePre.innerText = JSON.stringify(response, null, 2); return results; } catch (e) { alert( 'Geocode was not successful for the following reason: ' + String(e) ); } }
JavaScript
async function geocode(request) { clear(); const { LatLng } = await google.maps.importLibrary('core'); try { const response = await geocoder.geocode(request); const { results } = response; innerMap.setCenter(results[0].geometry.location); marker.position = new LatLng(results[0].geometry.location); mapElement.append(marker); responseDiv.style.display = 'block'; responsePre.innerText = JSON.stringify(response, null, 2); return results; } catch (e) { alert( 'Geocode was not successful for the following reason: ' + String(e) ); } }
Thiên vị khung nhìn
Bạn có thể hướng dẫn Dịch vụ mã hoá địa lý ưu tiên các kết quả trong một khung nhìn nhất định (được biểu thị dưới dạng 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 đối tượng chữ GeocoderRequest để xác định ranh giới của khung nhìn này. Xin lưu ý rằng việc thiên vị chỉ ưu tiên kết quả trong giới hạn; nếu có kết quả phù hợp hơn nằm ngoài các giới hạn này, thì kết quả đó có thể được đưa vào.
Ví dụ: mã địa lý cho "Winnetka" thường trả về vùng ngoại ô này của Chicago:
{ "types":["locality","political"], "formatted_address":"Winnetka, IL, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["locality","political"] },{ "long_name":"Illinois", "short_name":"IL", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location":[ -87.7417070, 42.1083080], "location_type":"APPROXIMATE" }, "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q" }
Tuy nhiên, việc chỉ định tham số bounds xác định hộp giới hạn cho Thung lũng San Fernando của Los Angeles sẽ dẫn đến việc mã hoá địa lý này trả về vùng lân cận có tên là "Winnetka" ở vị trí đó:
{ "types":["sublocality","political"], "formatted_address":"Winnetka, California, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["sublocality","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_3","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_2","political"] },{ "long_name":"California", "short_name":"CA", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location": [34.213171,-118.571022], "location_type":"APPROXIMATE" }, "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ" }
Thiên vị mã vùng
Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả thiên về một khu vực cụ thể một cách rõ ràng bằng cách sử dụng tham số region. Tham số này lấy 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ố). Các thẻ này liên kết trực tiếp với 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 (ví dụ: "GB" cho "Great Britain").
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ụ vùng gồm hai ký tự (định dạng Unicode CLDR). Tất cả cá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ó trong Thông tin chi tiết về phạm vi cung cấp của Google Maps Platform mới được hỗ trợ.
Bạn có thể gửi yêu cầu 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ì 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" có trường region được đặt thành 'es' (Tây Ban Nha) sẽ trả về thành phố của Tây Ban Nha:
{ "types":["locality","political"], "formatted_address":"Toledo, España", "address_components":[{ "long_name":"Toledo", "short_name":"Toledo", "types":["locality","political"] },{ "long_name":"Toledo", "short_name":"TO", "types":["administrative_area_level_2","political"] },{ "long_name":"Castilla-La Mancha", "short_name":"CM", "types":["administrative_area_level_1","political"] },{ "long_name":"España", "short_name":"ES", "types":["country","political"] }], "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y" }
Lọc thành phần
Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả địa chỉ bị giới hạn ở 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.
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à, hệ thống sẽ đá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:
routekhớp với tên dài hoặc tên ngắn của một tuyến đường.localitykhớp với các loại địa phương và địa phương phụ.administrativeAreakhớp với tất cả các cấp của khu vực hành chính.postalCodekhớp với mã bưu chính và tiền tố mã bưu chính.countrykhớp với tên quốc gia hoặc mã quốc gia gồm hai chữ cái theo chuẩn ISO 3166-1. Lưu ý: API này 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:
async function codeAddress(request: google.maps.GeocoderRequest) { clear(); geocoder.geocode({ componentRestrictions: { country: 'AU', postalCode: '2000' } }) .then((result) => { const { results } = result; innerMap.setCenter(results[0].geometry.location); let marker = new google.maps.marker.AdvancedMarkerElement({ map: innerMap, position: results[0].geometry.location }); }) .catch((e) => { alert('Geocode was not successful for the following reason: ' + e); }); };
Thực hiện khi không có kết quả
Đối với 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,
thì tham số này sẽ được điền sẵn. Nếu bạn cung cấp giá trị true cho tham số fulfillOnZeroResults,
thì lời hứa 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ừ lời hứa nếu có.
Sau đây là ví dụ về hành vi này đối với vĩ độ/kinh độ ở Nam Cực.
Mặc dù không có kết quả mã hoá địa lý ngược, nhưng chúng ta vẫn có thể in Plus Code trong promise 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: ${error}`); }); }
Thông tin 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ề thông tin mô tả địa chỉ để khám phá tính năng này.
Bạn có thể bật thông tin mô tả địa chỉ bằng cách sử dụng tham số extraComputations. Thêm extra_computations=ADDRESS_DESCRIPTORS vào yêu cầu mã hoá địa lý
, yêu cầu mã hoá địa lý ngược
hoặc yêu cầu mã hoá địa lý địa điểm
để nhận thông tin mô tả địa chỉ trong phản hồi.
Ví dụ về mã hoá địa lý địa điểm
Cụm từ tìm kiếm sau đây chứa địa chỉ của một địa điểm ở Delhi.
function addressDescriptorPlaceIdLookup() { geocoder.geocode({ geocoder.geocode({ 'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q', 'extraComputations': ['ADDRESS_DESCRIPTORS'] }, function(results, status) { if (status == 'OK') { console.log(results[0].address_descriptor); } else { window.alert('Geocode was not successful for the following reason: ' + status); } }); }
Ví dụ về mã hoá địa lý ngược
Truy vấn sau đây chứa giá trị vĩ độ/kinh độ cho một vị trí ở Delhi.
function addressDescriptorReverseGeocoding() { var latlng = new google.maps.LatLng(28.640964,77.235875); geocoder .geocode({ 'location': latlng, 'extraComputations': ["ADDRESS_DESCRIPTORS"], }) .then((response) => { console.log(response.address_descriptor); }) .catch((error) => { window.alert(`Error`); }); }
Ví dụ về thông tin 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ự mức độ liên quan bằng cách tính đến khoảng cách đến toạ độ được yêu cầu, mức độ phổ biến của địa danh và khả năng hiển thị của địa danh đó. Mỗi kết quả về địa danh đều chứa các giá trị sau:
place_idlà mã địa điểm của kết quả địa danh. Xem tổng quan về mã địa điểm.display_namelà tên hiển thị của địa danh và chứalanguage_codevàtext.straight_line_distance_meterslà khoảng cách điểm-điểm (tính bằng mét) giữa toạ độ đầu vào và kết quả địa danh.travel_distance_meterslà khoảng cách (tính bằng mét) khi di chuyển bằng mạng lưới đường bộ (bỏ qua các quy định hạn chế về đường bộ) giữa toạ độ đầu vào và kết quả về địa danh.spatial_relationshiplà mối quan hệ ước tính giữa toạ độ đầu vào và kết quả về địa danh:"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 ranh giới 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 địa danh hoặc điểm truy cập của địa danh."ACROSS_THE_ROAD"khi toạ độ đầu vào nằm đố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 nằm trên cùng tuyến đường với địa danh, nhưng không phải"BESIDES"hoặc"ACROSS_THE_ROAD"."AROUND_THE_CORNER"khi toạ độ đầu vào nằm dọc theo một tuyến đường vuông góc với địa danh (giới hạn ở một lượt rẽ)."BEHIND"khi toạ độ đầu vào gần địa danh về mặt không gian, nhưng lại xa điểm truy cập của địa danh đó.typeslà Loại địa điểm của địa danh.
Đối tượng areas chứa tối đa 3 phản hồi và chỉ giới hạn ở những địa điểm đại diện cho các khu vực nhỏ, chẳng hạn như khu lân cận, tiểu địa phương và khu phức hợp lớn. Những khu vực chứa toạ độ được yêu cầu sẽ được liệt kê trước và sắp xếp theo thứ tự từ nhỏ nhất đến lớn nhất. Mỗi kết quả areas chứa các giá trị sau:
place_idlà mã địa điểm của kết quả khu vực. Xem tổng quan về mã địa điểm.display_namelà tên hiển thị của khu vực và chứalanguage_codevàtext.containmentlà mối quan hệ chứa đựng ước tính giữa toạ độ đầu vào và kết quả khu vực:"NEAR"là mối quan hệ mặc định khi không có mối quan hệ nào sau đây được áp dụng."WITHIN"khi toạ độ đầu vào gần với tâm của khu vực."OUTSKIRTS"khi toạ độ đầu vào gần với cạnh của khu vực.
Phạm vi áp dụng của nội dung mô tả địa chỉ
Thông tin mô tả địa chỉ đã được phát hành rộng rãi ở Ấn Độ. Việc sử dụng thông tin mô tả địa chỉ ở Ấn Độ không phát sinh thêm chi phí và mức sử dụng được bao gồm trong Mã hoá địa lý (Ấn Độ) Essentials SKU hiện có.
Phản hồi
Tính năng này có ở tất cả các khu vực. Tính năng này đã được phát hành rộng rãi ở Ấn Độ và đang trong giai đoạn ra mắt thử nghiệm trước khi phát hành rộng rãi ở tất cả các khu vực khác. Chúng tôi rất mong nhận được ý kiến phản hồi:
- Riêng đối với các vấn đề liên quan đến khu vực Ấn Độ, hãy liên hệ với nhóm hỗ trợ.
- Để gửi ý kiến phản hồi về bản phát hành thử nghiệm, hãy gửi email cho chúng tôi theo địa chỉ address-descriptors-feedback@google.com.
- Hãy xem Thông tin chi tiết về phạm vi áp dụng của thông tin mô tả địa chỉ để biết thêm thông tin.
Mã hoá địa lý ngược (Tra cứu địa chỉ)
Thuật ngữ 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 thực hiện ngược lại, tức là 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à mã hoá đị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 mã hoá địa lý một giá trị vĩ độ/kinh độ và căn giữa bản đồ tại vị trí đó, đồng thời hiển thị cửa sổ thông tin có địa chỉ được định dạng. Nhấp vào vị trí bất kỳ trên bản đồ để mã hoá địa lý vị trí đó hoặc nhập toạ độ của riêng bạn.
TypeScript
let marker: google.maps.marker.AdvancedMarkerElement; async function init() { // Request the needed libraries. const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('geocoding'), google.maps.importLibrary('marker'), ]); // Get the gmp-map element. const mapElement = document.querySelector('gmp-map')!; // Get the inner map. const innerMap = mapElement.innerMap; // Get the latlng input box. const latLngQuery = document.getElementById('latlng') as HTMLInputElement; // Get the submit button. const submitButton = document.getElementById('submit')!; // Set the cursor to crosshair. innerMap.setOptions({ draggableCursor: 'crosshair', zoom: 13, mapTypeControl: false, }); // Create a marker for re-use. marker = new AdvancedMarkerElement({ map: innerMap, }); marker.anchorTop = '40px'; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); // Add a click event listener to the submit button. submitButton.addEventListener('click', () => { void geocodeLatLng(geocoder, innerMap, infoWindow); }); // Add a click event listener to the map. innerMap.addListener('click', (event: google.maps.MapMouseEvent) => { if (event.latLng) { latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`; void geocodeLatLng(geocoder, innerMap, infoWindow); } }); // Make an initial request upon loading. void geocodeLatLng(geocoder, innerMap, infoWindow); } async function geocodeLatLng( geocoder: google.maps.Geocoder, map: google.maps.Map, infoWindow: google.maps.InfoWindow ) { const input = (document.getElementById('latlng') as HTMLInputElement).value; const latlngStr = input.split(',', 2); const latlng = { lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1]), }; try { const { results } = await geocoder.geocode({ location: latlng }); if (results[0]) { marker.position = latlng; map.setCenter(latlng); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } catch (e) { window.alert('Geocoder failed due to: ' + String(e)); } } void init();
JavaScript
let marker; async function init() { // Request the needed libraries. const [{ InfoWindow }, { Geocoder }, { AdvancedMarkerElement }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('geocoding'), google.maps.importLibrary('marker'), ]); // Get the gmp-map element. const mapElement = document.querySelector('gmp-map'); // Get the inner map. const innerMap = mapElement.innerMap; // Get the latlng input box. const latLngQuery = document.getElementById('latlng'); // Get the submit button. const submitButton = document.getElementById('submit'); // Set the cursor to crosshair. innerMap.setOptions({ draggableCursor: 'crosshair', zoom: 13, mapTypeControl: false, }); // Create a marker for re-use. marker = new AdvancedMarkerElement({ map: innerMap, }); marker.anchorTop = '40px'; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); // Add a click event listener to the submit button. submitButton.addEventListener('click', () => { void geocodeLatLng(geocoder, innerMap, infoWindow); }); // Add a click event listener to the map. innerMap.addListener('click', (event) => { if (event.latLng) { latLngQuery.value = `${event.latLng.lat()}, ${event.latLng.lng()}`; void geocodeLatLng(geocoder, innerMap, infoWindow); } }); // Make an initial request upon loading. void geocodeLatLng(geocoder, innerMap, infoWindow); } async function geocodeLatLng(geocoder, map, infoWindow) { const input = document.getElementById('latlng').value; const latlngStr = input.split(',', 2); const latlng = { lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1]), }; try { const { results } = await geocoder.geocode({ location: latlng }); if (results[0]) { marker.position = latlng; map.setCenter(latlng); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } catch (e) { window.alert('Geocoder failed due to: ' + String(e)); } } void init();
CSS
/* * Always set the map height explicitly to define the size of the div element * that contains the map. */ gmp-map { height: 100%; } /* * Optional: Makes the sample page fill the window. */ html, body { height: 100%; margin: 0; padding: 0; font-family: Roboto, sans-serif; } #floating-panel { background-color: #fff; border-radius: 5px; box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px; margin: 10px; padding: 10px; font-family: Roboto, sans-serif; font-size: 1rem; } #latlng { width: 100%; font-family: Roboto, sans-serif; font-size: 1rem; margin-bottom: 4px; } #submit { font-size: 1rem; }
HTML
<html>
<head>
<title>Reverse Geocoding</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
<script>
// prettier-ignore
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "GOOGLE_MAPS_API_KEY"
});
</script>
</head>
<body>
<gmp-map center="0.714224, -73.961452" zoom="8" map-id="DEMO_MAP_ID">
<div id="floating-panel" slot="control-block-start-inline-start">
<p>
Click the map to reverse geocode, or add your own
coordinates.
</p>
<input
id="latlng"
type="text"
value="40.714224, -73.961452" /><br />
<input id="submit" type="button" value="Reverse Geocode" />
</div>
</gmp-map>
</body>
</html>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]. Trình mã hoá địa lý ngược thường trả về nhiều kết quả. Địa chỉ được mã hoá địa lý không chỉ là địa chỉ bưu chính mà còn là bất kỳ cách nào để đặt tên đị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 bộ mã hoá địa lý. Trình mã hoá địa lý ngược trả về tất cả các kết quả này.
Trình mã hoá địa lý ngược khớp với các thực thể chính trị (quốc gia, tỉnh, thành phố và 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ừ phù hợp nhất đến ít phù hợp nhất. Nhìn 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 vực lân cận, thành phố, quận, tiểu bang, v.v. Nếu muốn so khớp một địa chỉ chung chung hơn, bạn nên kiểm tra trường results[].types.
Lưu ý: Mã hoá địa lý ngược không phải là một môn 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 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ỉ cho một mã địa điểm nhất định. Mã địa điểm là một giá trị nhận dạng riêng biệ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 Roads trả về để lấy địa chỉ cho một điểm được bám dính. Để biết thêm thông tin về mã địa điểm, hãy xem phần 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:
addresslatLnglocationcomponentRestrictions
Ví dụ sau đây chấp nhận Mã địa điểm, tìm địa chỉ tương ứng và đặt bản đồ ở giữa vị trí đó. Thao tác này cũng hiển thị một cửa sổ thông tin cho biết địa chỉ được định dạng của địa điểm có liên quan:
TypeScript
// Initialize the map. async function init(): Promise<void> { const [{ Geocoder }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('geocoding'), google.maps.importLibrary('maps'), google.maps.importLibrary('marker'), ]); const mapElement = document.querySelector('gmp-map')!; const innerMap = mapElement.innerMap; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); document.getElementById('submit')!.addEventListener('click', () => { void geocodePlaceId(geocoder, innerMap, infoWindow); }); } // This function is called when the user clicks the UI button. async function geocodePlaceId( geocoder: google.maps.Geocoder, map: google.maps.Map, infoWindow: google.maps.InfoWindow ) { const placeId = (document.getElementById('place-id') as HTMLInputElement) .value; const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); const { results } = await geocoder.geocode({ placeId }); if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new AdvancedMarkerElement({ map, position: results[0].geometry.location, }); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } void init();
JavaScript
// Initialize the map. async function init() { const [{ Geocoder }, { InfoWindow }] = await Promise.all([ google.maps.importLibrary('geocoding'), google.maps.importLibrary('maps'), google.maps.importLibrary('marker'), ]); const mapElement = document.querySelector('gmp-map'); const innerMap = mapElement.innerMap; const geocoder = new Geocoder(); const infoWindow = new InfoWindow(); document.getElementById('submit').addEventListener('click', () => { void geocodePlaceId(geocoder, innerMap, infoWindow); }); } // This function is called when the user clicks the UI button. async function geocodePlaceId(geocoder, map, infoWindow) { const placeId = document.getElementById('place-id').value; const { AdvancedMarkerElement } = await google.maps.importLibrary('marker'); const { results } = await geocoder.geocode({ placeId }); if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new AdvancedMarkerElement({ map, position: results[0].geometry.location, }); infoWindow.setContent(results[0].formatted_address); infoWindow.open(map, marker); } else { window.alert('No results found'); } } void init();
Chọn API địa chỉ hoặc toạ độ phù hợp
Mở rộng phần sau để so sánh
google.maps.Geocoder
với các API khác của Google Maps Platform cho các tác vụ toạ độ và địa chỉ phổ biến:
So sánh Geocoder với các API khác của Google Maps Platform
| Mục tiêu của nhà phát triển | API hoặc phương thức được đề xuất | Trường hợp sử dụng |
|---|---|---|
Chuyển đổi địa chỉ đường phố đầy đủ thành toạ độ LatLng (mã hoá địa lý chuyển tiếp)
|
geocoder.geocode({ address })
(google.maps.Geocoder)
|
Sử dụng khi bạn đã có một chuỗi địa chỉ hoàn chỉnh, rõ ràng và cần toạ độ trên bản đồ. |
Chuyển đổi toạ độ GPS hoặc toạ độ bản đồ được nhấp ({ lat, lng }) thành địa chỉ đường phố mà con người có thể đọc được (mã hoá địa lý ngược)
|
geocoder.geocode({ location })
(google.maps.Geocoder)
|
Dùng để báo cáo tại hiện trường, thả ghim giao hàng hoặc hiển thị địa chỉ đường phố gần nhất cho một toạ độ. |
| Tìm kiếm địa chỉ theo kiểu nhập trước khi người dùng nhập vào trường nhập dữ liệu |
<gmp-place-autocomplete>
(PlaceAutocompleteElement)
|
Sử dụng cho các hộp tìm kiếm tương tác khi người dùng nhập, thay vì gọi Geocoder cho mỗi lần nhấn phím.
|
| Xác minh địa chỉ thanh toán hoặc địa chỉ giao hàng, chuẩn hoá các thành phần bưu chính hoặc kiểm tra khả năng giao hàng đến địa chỉ phụ và căn hộ |
Address Validation API
(POST https://addressvalidation.googleapis.com/v1:validateAddress)
|
Sử dụng cho quy trình thanh toán thương mại điện tử, biểu mẫu vận chuyển và quy trình làm việc phải xác nhận xem địa chỉ bưu chính hoặc số căn hộ/đơn vị có thể giao hàng hay không (điều mà Geocoder không xác minh).
|
Phân giải toạ độ (lat, lng) và dấu thời gian thành độ lệch UTC (rawOffset, dstOffset) và timeZoneId IANA
|
Time Zone API
(GET https://maps.googleapis.com/maps/api/timezone/json)
|
Sử dụng khi bạn cần mã múi giờ IANA, độ lệch UTC hoặc độ lệch giờ mùa hè cho một toạ độ và dấu thời gian (mà Geocoder không trả về).
|