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 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ỉ của 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ỉ tĩnh mà đã 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 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 cùng 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 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ở).
- Từ danh sách API trên Trang tổng quan, hãy tìm API mã hoá địa lý.
- Nếu thấy API này trong danh sách thì bạn đã hoàn tất. Nếu API không có trong danh sách, hãy bật API đó:
- Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị thẻ Library (Thư viện). Ngoài ra, trên trình đơn bên trái, hãy chọn Thư viện.
- Tìm kiếm Địa lý mã hóa API, sau đó chọn API đó từ danh sách kết quả.
- 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ả tiền 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ề giới hạn mới về định giá và sử dụng khi 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 theo các chính sách được mô tả về 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ột máy chủ bên ngoài. Do đó, bạn cần truyền 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 có thể truy cập vào dịch vụ mã hoá địa lý API Google Maps trong mã của mình thông qua đối tượng hàm khởi tạo google.maps.Geocoder
. Phương thức Geocoder.geocode()
sẽ bắt đầu một yêu cầu tới dịch vụ mã hoá địa lý, chuyển vào đó một đối tượng cố định GeocoderRequest
chứa các cụm từ đầu vào và phương thức gọi lại để thực thi khi nhận được phản hồi.
Đối tượng cố định 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 mà con người có thể đọc được. Bộ mã hoá địa lý thực hiện việc đảo ngược mã địa lý. 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 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ỉ của một mã địa điểm.
Tham số không bắt buộc:
bounds
–LatLngBounds
mà trong đó phân bổ mã địa lý sẽ hiển thị nổi bật hơn. Tham sốbounds
sẽ 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ề xu hướng khung nhìn dưới đây.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ề 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 2 ký tự (không phải số). Trong hầu hết trường hợp, các thẻ này sẽ ánh xạ trực tiếp tới giá trị 2 ký tự của ccTLD ("miền cấp cao nhất") quen thuộc. Tham sốregion
sẽ chỉ ảnh hưởng (nhưng không hạn chế hoàn toàn) kết quả từ bộ mã hoá địa lý. Vui lòng xem thêm thông tin về xu hướng mã vùng dưới đây.
Phản hồ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ố để giữ mã results
và 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ý duy nhất. Một 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 từ 0 thẻ trở lên xác định loại tính năng được trả về trong kết quả. Ví dụ: một mã địa lý của "pizza" trả về "vị trí" cho biết rằng "Thành phố Chicago" là một thành phố, đồng thời trả về giá trị "chính trị" cho biết đây là một pháp nhân 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ỉ 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 sự 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ề mặt 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 Hoa Kỳ).
Không phân tích cú pháp địa chỉ đã định dạng theo 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ẻ (trong đó phản hồi API sẽ bao gồm những thành phần này bên cạnh trường địa chỉ đã định dạng).
address_components[]
là một mảng chứa các thành phần riêng á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ỉ. Hãy 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 Bộ mã hoá địa lý trả về.short_name
là tên văn bản viết tắt cho 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_name
là "Alaska" vàshort_name
là "AK" 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 thực tế sau 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 bao gồm mọi pháp nhân chính trị có 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 pháp nhân chính trị có chứa địa chỉ cụ thể, bạn nên sử dụng tính năng mã hoá địa lý ngược, chuyển vĩ độ/kinh độ của địa chỉ dưới dạng thông số tới yêu cầu. - Định dạng của phản hồi không đảm bảo sẽ giữ nguyên giữa các yêu cầu. Cụ thể, số lượng
address_components
sẽ thay đổi tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng một địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại thành phần có thể thay đổi. Có thể thiếu một thành phần cụ thể trong phản hồi sau đó.
Xem thêm thông tin về các loại địa chỉ và loại thành phần địa chỉ dưới đây.
-
partial_match
cho 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 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 để xem có lỗi chính tả và/hoặc địa chỉ chưa hoàn chỉnh trong yêu cầu hay không.Khớp một phần thường xảy ra nhất với các địa chỉ đường phố không tồn tại trong khu vực mà bạn chuyển đến 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 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ả Phố Henry và phố Henrietta. Xin lưu ý rằng nếu một yêu cầu bao gồm thành phần địa chỉ bị sai chính tả, thì dịch vụ mã hóa đị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, có thể dùng với các API khác của Google. Ví dụ: bạn có thể sử dụngplace_id
với thư viện API Google Địa điểm để xem thông tin chi tiết về một doanh nghiệp địa phương, chẳng hạn như số điện thoại, giờ mở cửa, bài đánh giá của người dùng, v.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 khu vực có trong một mã bưu chính và chỉ hiển thị khi kết quả là một mã bưu chính chứa nhiều khu vực.geometry
chứa thông tin sau:location
chứa giá trị kinh độ,vĩ độ đượ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ượngLatLng
chứ không phải dưới dạng một chuỗi đã định dạng.location_type
lưu trữ dữ liệu bổ sung về vị trí đã chỉ định. Những giá trị sau đây hiện được hỗ trợ:ROOFTOP
cho biết kết quả được trả về phản ánh một mã địa lý chính xác.RANGE_INTERPOLATED
cho biết 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ư 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à đối với một địa chỉ đường phố.GEOMETRIC_CENTER
cho biết kết quả trả về là 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 đa giác (khu vực).APPROXIMATE
cho biết kết quả trả về chỉ mang tính tương đối.
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 Arallon. Về mặt kỹ thuật, quần đảo này là một phần của thành phố nhưng sẽ không được trả về trong khung nhìn.)
Các địa chỉ 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 nội dung
Bản địa hoá.)
Loại địa chỉ và loại thành phần địa chỉ
Mảng types[]
trong GeocoderResult cho biết loại địa chỉ. Mảng types[]
cũng có thể được trả về trong một GeocoderAddressComponent để cho biết loại của thành phần địa chỉ cụ thể. Các địa chỉ được bộ mã hoá địa lý trả về có thể có nhiều loại; những loại này có thể được xem là thẻ.
Ví dụ: nhiều thành phố được gắn thẻ thuộc loại political
và locality
.
Bộ mã hoá địa lý hỗ trợ và trả về các loại sau đây trong cả loại địa chỉ và loại thành phần địa chỉ:
street_address
cho biết địa chỉ đường phố chính xác.route
cho biết một tuyến đường có tên (chẳng hạn như "US 101").intersection
cho biết một nút giao chính, thường là của hai con đường chính.political
biểu thị 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ố cơ quan hành chính dân sự.country
chỉ pháp nhân chính trị quốc gia và thường là loại đơn đặt hàng cao nhất được Trình mã hoá địa lý trả về.administrative_area_level_1
cho biết pháp nhân dân sự cấp nhất thấp hơn cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là tiểu bang. Không phải quốc gia nào cũng 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 copyright_area_level_1 sẽ gần khớp với các phân mục theo tiêu chuẩn ISO 3166-2 và danh sách 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ã hóa địa lý của chúng tôi dựa trên nhiều tín hiệu và dữ liệu vị trí.administrative_area_level_2
cho biết pháp nhân dân sự cấp hai ở dưới cấp quốc gia. Ở Hoa Kỳ, các cấp hành chính này là hạt. Không phải quốc gia nào cũng có các cấp độ hành chính này.administrative_area_level_3
cho biết pháp nhân dân sự bên thứ ba có cấp độ thấp hơn cấp quốc gia. Loại này biểu thị một phân chia dân sự nhỏ. 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 pháp nhân dân sự cấp 4 thấp hơn cấp quốc gia. Loại này biểu thị một phân chia dân sự nhỏ. 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 pháp nhân dân sự cấp 5 ở dưới cấp quốc gia. Loại này biểu thị một phân chia dân sự nhỏ. 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
chỉ một pháp nhân dân sự cấp 6 ở dưới cấp quốc gia. Loại này biểu thị một phân chia dân sự nhỏ. 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
chỉ một pháp nhân dân sự cấp 7 ở dưới cấp quốc gia. Loại này biểu thị một phân chia dân sự nhỏ. Không phải quốc gia nào cũng có các cấp độ hành chính này.colloquial_area
là tên thay thế thường dùng của thực thể.locality
cho biết một pháp nhân chính trị thành phố hoặc thị trấn được thành lập.sublocality
cho biết pháp nhân dân sự cấp thứ nhất 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
đếnsublocality_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
chỉ một vùng lân cận được đặt tênpremise
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ó tên chungsubpremise
chỉ ra thực thể bậc nhất bên dưới một vị trí được đặt tên, thường là một toà nhà số ít trong một tập hợp các toà nhà có tên chungplus_code
cho biết tham chiếu vị trí đã mã hoá, bắt nguồn từ vĩ độ và kinh độ. Mã cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những nơi không tồn tại (nơi các toà nhà không được đánh số hoặc đường phố không được đặt tên). Hãy xem https://plus.codes để biết thông tin chi tiết.postal_code
cho biết mã bưu chính được dùng để xử lý thư bưu điện 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 tên.point_of_interest
cho biết một địa điểm yêu thích đã đặt tên. Thông thường, những "POI" này là những thực thể nổi bật ở địa phương và khó đưa vào một danh mục khác, chẳng hạn như "Empire State toà nhà" hoặc "Tháp Eiffel".
Danh sách các loại trống cho biết không có loại nào xác định cho thành phần địa chỉ cụ thể, ví dụ: Lieu-dit ở Pháp.
Ngoài các loại ở trên, các 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ợ việc chỉ đường.point_of_interest
cho biết một địa điểm yêu thích đã đặt tên.parking
cho biết 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
) được dùng cho các địa chỉ gửi thư ở một số quốc gia.room
cho biết phòng của một địa chỉ toà nhà.street_number
cho biết số nhà chính xác.bus_station
,train_station
vàtransit_station
cho biết vị trí của xe buýt, xe lửa hoặc điểm dừng 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ý đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu bộ mã hoá địa lý được chuyển mộtaddress
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 rằng truy vấn (address
,components
hoặclatlng
) bị thiếu."UNKNOWN_ERROR"
cho biết rằng 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 rằng yêu cầu đã hết thời gian chờ hoặc đã xảy ra sự cố khi kết nối 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ý cho 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 chuyển dưới dạng giá trị cố định của hàm ẩn danh.
var geocoder; var map; function initialize() { geocoder = new google.maps.Geocoder(); var latlng = new google.maps.LatLng(-34.397, 150.644); var mapOptions = { zoom: 8, center: latlng } map = new google.maps.Map(document.getElementById('map'), mapOptions); } function codeAddress() { var address = document.getElementById('address').value; geocoder.geocode( { 'address': address}, function(results, status) { if (status == 'OK') { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } else { alert('Geocode was not successful for the following reason: ' + status); } }); } <body onload="initialize()"> <div id="map" style="width: 320px; height: 480px;"></div> <div> <input id="address" type="textbox" value="Sydney, NSW"> <input type="button" value="Encode" onclick="codeAddress()"> </div> </body>
Xu hướng 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 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 có nhiề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 hộp giới hạn cho Thung lũng San Fernando của Los Angeles sẽ dẫn đến việc mã địa lý trả về vùng lân cận có tên "Winnetka" ở vị trí đó:
{ "types":["sublocality","political"], "formatted_address":"Winnetka, California, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["sublocality","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_3","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_2","political"] },{ "long_name":"California", "short_name":"CA", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location": [34.213171,-118.571022], "location_type":"APPROXIMATE" }, "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ" }
Xu hướng mã vùng
Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả sai lệch cho một khu vực cụ thể bằng cách sử dụng tham số region
một cách rõ ràng. Thông số này sẽ lấy một mã vùng, được chỉ định dưới dạng một thẻ phụ vùng Unicode gồm hai ký tự (không phải dạng 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ới 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. Mã này đôi khi khác với giá trị ccTLD (ví dụ: "GB" đối với "Vương quốc Anh").
Khi sử dụng tham số region
:
- Chỉ chọn 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ụ khu vực hai ký tự (định dạng Unicode CLDR). Tất cả các dữ liệu đầu vào khác đều sẽ dẫn đến lỗi.
- Chỉ những quốc gia và khu vực được liệt kê trong Thông tin chi tiết về phạm vi lập chỉ mục của Nền tảng Google Maps mới được hỗ trợ.
Có thể gửi yêu cầu mã hóa địa lý đến mọi miền mà trong đó ứng dụng Google Maps chính cung cấp mã hóa địa lý. Xin lưu ý rằng xu hướng chỉ ưu tiên kết quả cho một miền cụ thể; nếu các kết quả phù hợp hơn tồn tại 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" sẽ trả về kết quả này vì miền mặc định của Dịch vụ mã hóa đị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ột 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ề các kết quả địa chỉ bị giới hạn ở một khu vực cụ thể, bằng cách 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 pháp sửa chính tả và 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ả các bộ lọc thành phần. Tức là cách này 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:
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 loại địa phương và cụm dân cư.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 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); } }); }
Mã hóa địa lý ngược (Tra cứu địa chỉ)
Thuật ngữ mã hoá địa lý thường đề cập đến việc dịch 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 chuyển đổi, dịch một vị trí trên bản đồ thành một địa chỉ mà con người có thể đọc được, được gọi là mã hoá địa lý ngược.
Thay vì cung cấp address
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 thông số location
.
Ví dụ sau đây sẽ mã hoá địa lý một giá trị vĩ độ/kinh độ và căn giữa bản đồ tại vị trí đó, hiển thị một cửa sổ thông tin có địa chỉ đã đị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;
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;
Thử mẫu
Xin lưu ý rằng trong ví dụ trước, chúng ta đã hiển thị kết quả đầu tiên bằng cách chọn results[0]
. Bộ mã hoá địa lý ngược thường trả về nhiều kết quả. Địa chỉ được mã hoá địa lý không chỉ là địa chỉ bưu điện, mà còn là bất kỳ
cách nào để đặt tên theo địa lý cho một vị trí. Ví dụ: khi mã hoá địa lý một điểm tại thành phố Chicago, điểm được mã hoá địa lý có thể được gắn nhãn là địa chỉ đường phố, là thành phố (Chicago), tiểu bang của nó (Illinois) hoặc quốc gia (Hoa Kỳ). Tất cả đều là địa chỉ tới bộ mã hoá địa lý. Bộ mã hoá địa lý ngược sẽ trả về tất cả các kết quả này.
Bộ 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à vùng lân cận), địa chỉ đường phố và mã bưu chính.
Dưới đây là ví dụ về danh sách các địa chỉ mà truy vấn trên có thể trả về:
results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA" results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA" results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA" results[3].formatted_address: "Brooklyn, NY, USA" results[4].formatted_address: "New York, NY, USA" results[5].formatted_address: "Brooklyn, NY 11211, USA" results[6].formatted_address: "Kings County, NY, USA" results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA" results[8].formatted_address: "New York Metropolitan Area, USA" results[9].formatted_address: "New York, USA"
Các địa chỉ được trả về theo thứ tự phù hợp nhất đến ít nhất. Nhìn chung, địa chỉ chính xác hơn là kết quả nổi bật nhất, như trong trường hợp này.
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 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ể xác định địa chỉ gần nhất trong phạm vi dung sai nhất định.
Truy xuất địa chỉ cho một 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 API Đường trả về để lấy địa chỉ của một điểm chụp nhanh. Để biết thêm thông tin về mã địa điểm, hãy xem bài viết tổng quan về mã địa điểm.
Khi 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 hiển thị một cửa sổ thông tin cho thấy địa chỉ đã đị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;
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;