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 mã hoá địa lý thành một địa chỉ mà con người có thể đọc được (xem Mã hóa địa lý đảo (Tra cứu địa chỉ)).
Bạn cũng có thể sử dụng bộ mã hoá địa lý để tìm địa chỉ của một mã địa điểm đã cho.
API JavaScript của Maps cung cấp Lớp bộ mã hoá địa lý cho mã hoá địa lý và mã hoá địa lý đảo ngược một cách linh hoạt từ hoạt động đầu vào của người dùng. Nếu thay vì bạn muốn mã hoá địa lý theo đị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 JavaScript của Maps, đầu tiên hãy đảm bảo rằng API mã hóa địa lý được bật trong Google Cloud Console, trong cùng một dự án bạn thiết lập cho API Maps JavaScript.
Cách xem danh sách API đã bật:
- Chuyển đến Bảng điều khiển Google Cloud.
- Nhấp vào nút Select a project (Chọn dự án), rồi chọn chính dự án mà bạn đã thiết lập cho API Maps JavaScript rồi nhấp vào Mở.
- Trong danh sách API trên Trang tổng quan, hãy tìm API mã hoá địa lý.
- 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,
bật:
- Ở đầu trang, hãy chọn ENABLE API (BẬT API) để hiển thị Thẻ Thư viện. Ngoài ra, từ trình đơn bên trái, hãy chọn Thư viện.
- Tìm kiếm API mã hóa địa lý, sau đó chọn từ danh sách kết quả.
- Chọn BẬT. Khi quá trình này kết thúc, API mã hoá địa lý xuất hiện trong danh sách API trên Trang tổng quan.
Giá và chính sách
Giá
Kể từ ngày 16 tháng 7 năm 2018, gói giá mới trả theo mức dùng đã bắt đầu có hiệu lực. cho Bản đồ, Tuyến đường và Địa điểm. Để tìm hiểu thêm về mức giá và mức sử dụng mới các giới hạn đối với việc sử dụng dịch vụ Mã hoá địa lý JavaScript, hãy xem Việc sử dụng và thanh toán cho API mã hóa địa lý.
Chính sách
Việc sử dụng dịch vụ Mã hóa địa lý phải tuân theo các chính sách nêu trên cho API mã hóa địa lý.
Yêu cầu mã hoá địa lý
Truy cập dịch vụ Mã hoá địa lý là không đồng bộ, do API Google Maps cần thực hiện lệnh gọi đến máy chủ bên ngoài. Vì lý do đó, bạn cần chuyển phương thức callback thực thi sau khi hoàn tất yêu cầu. Chiến dịch này phương thức gọi lại xử lý(các) kết quả. Lưu ý rằng bộ mã hoá địa lý có thể trả về nhiều kết quả.
Bạn truy cập vào dịch vụ mã hoá địa lý của API Google Maps trong mã của mình thông qua
Đối tượng hàm khởi tạo google.maps.Geocoder
. Chiến lược phát hành đĩa đơn
Phương thức Geocoder.geocode()
bắt đầu một yêu cầu mã hoá địa lý
dịch vụ, truyền vào đó một đối tượng 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.
Hằng đối tượng GeocoderRequest
chứa các trường sau:
{ address: string, location: LatLng, placeId: string, bounds: LatLngBounds, componentRestrictions: GeocoderComponentRestrictions, region: string }
Tham số bắt buộc: Bạn phải cung cấp một và chỉ một trong các trường sau:
address
— Địa chỉ mà bạn muốn mã hoá địa lý.
hoặc
location
—LatLng
(hoặcLatLngLiteral
) mà bạn muốn có được thông tin gần nhất, địa chỉ mà con người có thể đọc được. Bộ mã hoá địa lý thực hiện mã địa lý đảo ngược. Xem Mã hóa địa lý đảo ngược để biết thêm thông tin.
hoặc
placeId
— Mã địa điểm của địa điểm mà bạn muốn để lấy địa chỉ gần nhất mà con người có thể đọc được. Xem thêm về truy xuất địa chỉ cho mã địa điểm.
Các thông số không bắt buộc:
bounds
— Cụm từLatLngBounds
để làm sai lệch kết quả mã hoá địa lý nổi bật hơn. Tham sốbounds
sẽ chỉ ảnh hưởng chứ không hạn chế hoàn toàn đến kết quả từ bộ mã hoá địa lý. Xem thông tin khác về xu hướng khung nhìn trong phần dưới đây.componentRestrictions
– Dùng để giới hạn kết quả ở một khu vực cụ thể. Xem thêm thông tin về lọc thành phần ở bên dưới.region
– Mã vùng, được chỉ định làm được chỉ định dưới dạng thẻ phụ vùng Unicode gồm hai ký tự (không phải số). Trong hầu hết trong một số trường hợp, các thẻ này ánh xạ trực tiếp đến ccTLD (miền cấp cao nhất) quen thuộc 2 ký tự. Tham sốregion
sẽ chỉ ảnh hưởng, không hạn chế hoàn toàn, các kết quả từ bộ mã hoá địa lý. Xem thêm thông tin về xu hướng mã vùng bên dưới.extraComputations
– Giá trị duy nhất được phép cho trường này tham số làADDRESS_DESCRIPTORS
. Xem mã mô tả địa chỉ để biết thêm chi tiết.fulfillOnZeroResults
— Thực hiện lời hứa về trạng thái ZERO_RESULT trong của bạn. Điều này có thể xảy ra vì ngay cả khi không có kết quả mã hoá địa lý thì vẫn có thể trường mức độ phản hồi bổ sung được trả về. Xem Thực hiện khi không có kết quả để biết thêm thông tin.
Câu trả lời mã hoá địa lý
Dịch vụ Mã hoá địa lý yêu cầu phương pháp gọi lại để thực thi khi truy xuất
của các kết quả của bộ mã hoá địa lý. Lệnh gọi lại này sẽ 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ý. Yêu cầu mã hoá địa lý có thể trả về nhiều đối tượng kết quả:
results[]: { types[]: string, formatted_address: string, address_components[]: { short_name: string, long_name: string, postcode_localities[]: string, types[]: string }, partial_match: boolean, place_id: string, postcode_localities[]: string, geometry: { location: LatLng, location_type: GeocoderLocationType viewport: LatLngBounds, bounds: LatLngBounds } }
Các trường này được giải thích bên dưới:
types[]
là một mảng cho biết loại địa chỉ của kết quả được trả về. Mảng này chứa một tập hợp không hoặc nhiều thẻ xác định loại đối tượng được trả về trong kết quả. Ví dụ: một mã địa lý của "Chicago" trả về "địa phương" điều này cho biết rằng "Chicago" là thành phố và cũng trả về "chính trị" cho biết đây là một báo cáo chính trị thực thể. Xem thêm thông tin về loại địa chỉ và thành phần địa chỉ dưới đây.formatted_address
là một chuỗi chứa thông tin con người có thể đọc được địa chỉ 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. Lưu ý rằng một số quốc gia khác (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 do các quy định hạn chế về giấy phép.
Địa chỉ được định dạng bao gồm một hoặc nhiều địa chỉ theo logic thành phần. Ví dụ: địa chỉ "111 8th Avenue, New York, NY" bao gồm các thành phần sau: "111" (số nhà), "Đại lộ số 8" (tuyến đường), "New York" (thành phố) và "NY" (tiểu bang của Hoa Kỳ).
Không phân tích cú pháp địa chỉ đã định dạng theo phương thức lập trình. Thay vào đó, bạn nên sử dụng các thành phần địa chỉ riêng lẻ, trong đó phản hồi của API còn bao gồm vào trường địa chỉ được định dạng.
address_components[]
là một mảng chứa các tham số riêng biệt áp dụng cho địa chỉ này.Mỗi thành phần địa chỉ thường chứa các trường sau:
types[]
là một mảng cho biết loại của thành phần địa chỉ. Xem danh sách các loại được hỗ trợ.long_name
là văn bản mô tả đầy đủ hoặc tên của địa chỉ do Bộ mã hoá địa lý trả về.short_name
là tên viết tắt dạng văn bản cho địa chỉ thành phần, nếu có. Ví dụ: thành phần địa chỉ của trạng thái Alaska có thể cólong_name
là "Alaska" và mộtshort_name
trong số "AK" bằng cách sử dụng ký tự viết tắt gồm 2 chữ cái của bưu điện.
Vui lòng lưu ý những thông tin sau về
address_components[]
mảng:- Mảng thành phần địa chỉ có thể chứa nhiều thành phần hơn so với
formatted_address
. - Mảng này không nhất thiết phải bao gồm tất cả các pháp nhân chính trị
chứa địa chỉ, ngoài những địa chỉ được nêu trong
formatted_address
. Cách truy xuất tất cả pháp nhân chính trị có chứa địa chỉ cụ thể, bạn nên sử dụng mã hoá địa lý ngược, truyền vĩ độ/kinh độ của địa chỉ dưới dạng một tham số cho yêu cầu. - Định dạng của phản hồi không được đảm bảo sẽ giống nhau giữa
yêu cầu. Cụ thể, số lượng
address_components
sẽ khác nhau tuỳ theo địa chỉ được yêu cầu và có thể thay đổi theo thời gian đối với cùng địa chỉ. Một thành phần có thể thay đổi vị trí trong mảng. Loại của thành phần có thể thay đổi. Một thành phần cụ thể có thể bị thiếu trong câu trả lời sau đó.
Xem thêm thông tin về loại địa chỉ và thành phần địa chỉ dưới đây.
-
partial_match
cho biết bộ mã hoá địa lý không trả về khớp chính xác với 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 không địa chỉ không đầy đủ.Kết quả khớp một phần thường xảy ra với các địa chỉ đường phố không tồn tại trong địa phương mà bạn gửi 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 tổ dân phố. Ví dụ: "Hillpar St, Bristol, UK" sẽ trả về kết quả khớp một phần cho cả hai Đường Henry và Đường Henryetta. Xin lưu ý rằng nếu yêu cầu bao gồm thành phần địa chỉ bị sai chính tả, dịch vụ mã hoá địa lý có thể đề xuất phương án thay thế của bạn. Các đề xuất được kích hoạt theo cách này cũng sẽ được đánh dấu là một phần khớp.
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 Google Địa điểm API để 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.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ã bưu chính và chỉ xuất hiện khi kết quả là một mã bưu chính mã chứa nhiều địa phương.geometry
chứa những thông tin sau:location
chứa giá trị kinh độ,vĩ độ được mã hoá địa lý. 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 chuỗi được định dạng.location_type
lưu trữ dữ liệu bổ sung về vị trí. Các giá trị sau hiện đang được hỗ trợ:ROOFTOP
cho biết rằng 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 giá trị gần đúng (thường là trên đường) nội suy giữa hai điểm chính xác (chẳng hạn như dưới dạng giao điểm). Kết quả nội suy thường được trả về khi không thể sử dụng mã địa lý trên mái nhà cho địa chỉ đường phố.GEOMETRIC_CENTER
cho biết kết quả trả về là trung tâm hình học của kết quả như hình nhiều đường (ví dụ: đường phố) hoặc đa giác (khu vực).APPROXIMATE
cho biết rằng kết quả trả về là gần đúng.
viewport
lưu trữ khung nhìn đề xuất cho kết quả được trả về.bounds
(không bắt buộc phải trả lại) 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. (Đối với Ví dụ: San Francisco bao gồm Farallon Đảo, là một phần về mặt kỹ thuật của thành phố, nhưng không được đượ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 lựa chọn ưu tiên của trình duyệt
chế độ cài đặt ngôn ngữ hoặc ngôn ngữ được chỉ định khi tải API JavaScript
bằng cách sử dụng tham số language
. (Để biết thêm thông tin, hãy xem
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 thành phần địa chỉ cụ thể. Địa chỉ đã trả về
do bộ mã hoá địa lý có thể có nhiều loại; có thể được coi là thẻ.
Ví dụ: nhiều thành phố được gắn thẻ bằng political
và
Loại locality
.
Các loại sau đây được bộ mã hoá địa lý hỗ trợ và trả về 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
biểu thị giao lộ chính, thường là hai các con đường chính.political
cho biết một pháp nhân chính trị. Thông thường, loại này biểu thị một đa giác của một số hành chính dân sự.country
cho biết pháp nhân chính trị quốc gia và là thường là loại đơn đặt hàng cao nhất mà Bộ mã hoá địa lý trả về.administrative_area_level_1
biểu thị một dân sự bậc nhất pháp nhân dưới cấp quốc gia. Tại Hoa Kỳ, những chỉ số này cấp hành chính là các tiểu bang. Không phải quốc gia nào cũng có các triển lãm này cấp hành chính. Trong hầu hết các trường hợp, Administrative_area_level_1 tên ngắn sẽ phù hợp với các phân mục ISO 3166-2 và các phân mục khác danh sách lưu hành; 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
biểu thị một dân sự bậc hai pháp nhân dưới cấp quốc gia. Tại Hoa Kỳ, những chỉ số này cấp hành chính là các hạt. Không phải quốc gia nào cũng có các triển lãm này cấp hành chính.administrative_area_level_3
biểu thị một dân sự bậc ba pháp nhân dưới cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.administrative_area_level_4
biểu thị một dân sự bậc 4 pháp nhân dưới cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.administrative_area_level_5
biểu thị dân sự bậc 5 pháp nhân dưới cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.administrative_area_level_6
biểu thị một dân sự bậc 6 pháp nhân dưới cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.administrative_area_level_7
biểu thị một dân sự bậc 7 pháp nhân dưới cấp quốc gia. Loại này biểu thị một phân cấp dân sự nhỏ. Không phải quốc gia nào cũng thể hiện các cấp hành chính này.colloquial_area
cho biết một tên thay thế thường dùng cho thực thể.locality
cho biết một thành phố hoặc thị trấn chính trị đã được hợp nhất thực thể.sublocality
cho biết pháp nhân dân sự bậc 1 thuộc cấp dưới địa phương. Đối với một số vị trí, bạn có thể nhận được một trong những loại bổ sung:sublocality_level_1
thànhsublocality_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ý.neighborhood
biểu thị vùng lân cận được đặt tênpremise
cho biết vị trí được đặt tên, thường là một toà nhà hoặc bộ sưu tập các toà nhà có tên phổ biếnsubpremise
cho biết thực thể đơn đặt hàng đầu tiên bên dưới một thực thể có tên một vị trí, thường là một toà nhà đơn lẻ trong một tập hợp các toà nhà có một tên thường gọiplus_code
cho biết tham chiếu vị trí được mã hoá, dẫn xuất so với vĩ độ và kinh độ. Plus code có thể được dùng để thay thế cho địa chỉ đường phố ở nơi không tồn tại (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). Xem https://plus.codes để biết thông tin chi tiết.postal_code
cho biết mã bưu chính dùng để xử lý địa chỉ bưu chính thư trong quốc gia.natural_feature
biểu thị một đối tượng tự nhiên nổi bật.airport
cho biết một sân bay.park
biểu thị một công viên có tên.point_of_interest
cho biết một địa điểm yêu thích đã được đặt tên. Thông thường, những "POI" này là thực thể cục bộ nổi bật không dễ dàng phù hợp trong một danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Tháp Eiffel".
Danh sách trống các loại cho biết không có loại nào đã biết cho thuộc tính cụ thể thành phần địa chỉ, ví dụ: Lieu-dit ở Pháp.
Ngoài những thành phần nêu trên, thành phần địa chỉ có thể bao gồm các loại dưới đây.
Lưu ý:Đây chưa phải là danh sách đầy đủ và có thể thay đổi.
floor
cho biết tầng của một địa chỉ toà nhà.establishment
thường cho biết một địa điểm đã đượ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 địa điểm yêu thích đã được đặt tên.parking
biểu thị bãi đỗ xe hoặc bãi đỗ xe.post_box
cho biết một hộp thư cụ thể.postal_town
biểu thị một nhóm các khu vực địa lý, chẳng hạn nhưlocality
vàsublocality
, dùng cho địa chỉ gửi thư ở một số quốc gia.room
biểu thị phòng có địa chỉ tòa nhà.street_number
cho biết số nhà chính xác.bus_station
,train_station
vàtransit_station
cho biết vị trí của xe buýt, tàu hoặc công cộng đ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à vào lúc ít nhất một mã địa lý đã được trả về."ZERO_RESULTS"
cho biết mã địa lý đã được mã hoá thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu bộ mã hoá địa lý đã được thông qua mộ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
)."UNKNOWN_ERROR"
cho biết rằng yêu cầu không thể được xử lý do lỗi máy chủ. Yêu cầu có thể thành công nếu bạn hãy thử lại."ERROR"
cho biết yêu cầu đã hết thời gian chờ hoặc có xảy ra sự cố khi liên hệ với máy chủ Google. Yêu cầu có thể thành công nếu bạn hãy thử lại.
Trong ví dụ này, chúng tôi mã hoá địa lý một địa chỉ và đặt một điểm đánh dấu tại điểm đánh dấu được trả về. vĩ độ và kinh độ. Lưu ý rằng trình xử lý được chuyển dưới dạng hằng 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ý tìm kiếm kết quả trong một
khung nhìn (được biểu thị dưới dạng một hộp giới hạn). Bạn có thể thực hiện bằng cách đặt
Tham số bounds
trong đối tượng GeocoderRequest
giá trị cố định để xác định giới hạn của khung nhìn này. Lưu ý rằng chỉ có xu hướng
ư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 những giới hạn này thì chúng có thể được đưa vào.
Ví dụ: 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
đối với kết quả trả về theo mã địa lý này của Thung lũng San Fernando của Los Angeles
khu phố có tên là "Winnetka" ở vị trí đó:
{ "types":["sublocality","political"], "formatted_address":"Winnetka, California, USA", "address_components":[{ "long_name":"Winnetka", "short_name":"Winnetka", "types":["sublocality","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_3","political"] },{ "long_name":"Los Angeles", "short_name":"Los Angeles", "types":["administrative_area_level_2","political"] },{ "long_name":"California", "short_name":"CA", "types":["administrative_area_level_1","political"] },{ "long_name":"United States", "short_name":"US", "types":["country","political"] }], "geometry":{ "location": [34.213171,-118.571022], "location_type":"APPROXIMATE" }, "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ" }
Xu hướng mã vùng
Bạn có thể đặt Dịch vụ mã hoá địa lý để trả về kết quả có xu hướng
khu vực rõ ràng bằng cách sử dụng tham số region
. Thông số này
lấy một mã vùng, được chỉ định dưới dạng Unicode hai ký tự (không phải số)
thẻ phụ khu vực. Các thẻ này liên kết trực tiếp với ccTLD (miền cấp cao nhất) quen thuộc
giá trị gồm hai ký tự, chẳng hạn như "uk" trong "co.uk" ví dụ: Trong một số trường hợp,
Thẻ region
cũng hỗ trợ mã ISO-3166-1 mà đôi khi
khác với các giá trị ccTLD (ví dụ: "GB" đối với "Vương quốc Anh").
Khi sử dụng tham số region
:
- Chỉ chỉ định một quốc gia hoặc khu vực. Nhiều giá trị sẽ bị bỏ qua và có thể khiến yêu cầu không thành công.
- Chỉ sử dụng thẻ phụ vùng có 2 ký tự (định dạng CLDR Unicode). Tất cả giá trị khác sẽ dẫn đến lỗi.
- Chỉ những quốc gia và khu vực được liệt kê trong Google Thông tin chi tiết về phạm vi áp dụng của Nền tảng Maps được hỗ trợ.
Yêu cầu mã hoá địa lý có thể được gửi cho mọi miền mà Ứng dụng Google Maps cung cấp mã hóa địa lý. Lưu ý rằng xu hướng chỉ ưu tiên kết quả cho một miền cụ thể; nếu kết quả phù hợp hơn bên ngoài miền này thì có thể bao gồm.
Ví dụ: mã địa lý cho "Toledo" sẽ trả về kết quả này, theo mặc định dà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ột mã địa lý của "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ế
vào 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ợ
phương pháp sửa chính tả và so khớp một phần giống như các phương pháp mã hoá địa lý khác
yêu cầu.
Bộ mã hoá địa lý chỉ trả về những kết quả khớp với tất cả thành phần bộ lọc. Tức là phương thức này đánh giá các thông số của bộ lọc dưới dạng AND, chứ không phải HOẶC
Bộ lọc thành phần bao gồm một hoặc nhiều mục sau:
route
khớp với tên dài hoặc tên ngắn của một tuyến đường.locality
khớp với địa phương và loại địa phương.administrativeArea
khớp với tất cả cấp 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 một tên quốc gia hoặc một chữ cái gồm hai chữ cái ISO 3166-1 . Lưu ý: API tuân thủ tiêu chuẩn ISO đối với để xác định quốc gia và quá trình lọc hoạt động hiệu quả nhất khi sử dụng mã ISO tương ứng của quốc gia.
Ví dụ sau minh hoạ việc sử dụng
Tham số componentRestrictions
để lọc theo
country
và postalCode
:
function codeAddress() { geocoder.geocode({ componentRestrictions: { country: 'AU', postalCode: '2000' } }, function(results, status) { if (status == 'OK') { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location }); } else { window.alert('Geocode was not successful for the following reason: ' + status); } }); }
Thực hiện khi không có kết quả
Đối với mã hoá địa lý ngược, theo mặc định, cam kết sẽ bị thực hiện trên status=ZERO_RESULTS
. Tuy nhiên,
các trường mức phản hồi bổ sung của plus_code
và address_descriptor
có thể vẫn đang
đượ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
,
lời hứa không bị hỏng và bạn có thể truy cập vào các trường bổ sung này từ lời hứa nếu có.
Sau đây là ví dụ về hành vi này đối với một vĩ độ/kinh độ ở Nam Cực.
Mặc dù không có kết quả mã hoá địa lý ngược, chúng ta vẫn có thể in plus code
trong lời hứa nếu chúng ta đặt fulfillOnZeroResults=true
.
function addressDescriptorReverseGeocoding() { var latlng = new google.maps.LatLng(-75.290330, 38.653861); geocoder .geocode({ 'location': latlng, 'fulfillOnZeroResults': true, }) .then((response) => { console.log(response.plus_code); }) .catch((error) => { window.alert(`Error`); }); }
Nội dung mô tả địa chỉ
Phần mô tả địa chỉ bao gồm thông tin bổ sung giúp mô tả vị trí bằng cách sử dụng các địa danh và khu vực. Kiểm tra bản minh hoạ về nội dung mô tả địa chỉ để khám phá tính năng này.
Bạn có thể bật mã mô tả địa chỉ thông qua extraComputations
. Bao gồm extra_computations=ADDRESS_DESCRIPTORS
trong yêu cầu mã hóa địa lý
, đảo ngược yêu cầu mã hoá địa lý
hoặc yêu cầu mã hoá địa lý địa điểm
để nhận mã mô tả địa chỉ trong phản hồi của bạn.
Ví dụ về mã hoá địa lý địa điểm
Truy vấn sau có chứa địa chỉ của một địa điểm ở Delhi.
function addressDescriptorPlaceIdLookup() { geocoder.geocode({ 'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q', 'extraComputations': ['ADDRESS_DESCRIPTORS'] }, function(results, status) { if (status == 'OK') { console.log(results[0].address_descriptor); } else { window.alert('Geocode was not successful for the following reason: ' + status); } }); }
Ví dụ về mã hoá địa lý ngược
Truy vấn sau chứa giá trị vĩ độ/kinh độ 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ề phần mô tả địa chỉ
Sau đây là ví dụ về address_descriptor
.
{ "address_descriptor" : { "areas" : [ { "containment" : "OUTSKIRTS", "display_name" : { "language_code" : "en", "text" : "Turkman Gate" }, "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs" }, { "containment" : "OUTSKIRTS", "display_name" : { "language_code" : "en", "text" : "Chandni Chowk" }, "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI" }, { "containment" : "NEAR", "display_name" : { "language_code" : "en", "text" : "Katar Ganj" }, "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY" } ], "landmarks" : [ { "display_name" : { "language_code" : "en", "text" : "Delite Cinema" }, "straight_line_distance_meters" : 29.9306755065918, "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM", "travel_distance_meters" : 418.7794799804688, "spatial_relationship" : "ACROSS_THE_ROAD", "types" : [ "establishment", "movie_theater", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "YES Bank" }, "straight_line_distance_meters" : 66.83731079101562, "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ", "travel_distance_meters" : 489.0340270996094, "spatial_relationship" : "DOWN_THE_ROAD", "types" : [ "bank", "establishment", "finance", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "UCO Bank" }, "straight_line_distance_meters" : 25.38849639892578, "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM", "travel_distance_meters" : 403.2246398925781, "spatial_relationship" : "ACROSS_THE_ROAD", "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ] }, { "display_name" : { "language_code" : "en", "text" : "Delhi By Cycle Meeting Point" }, "straight_line_distance_meters" : 44.02867126464844, "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM", "travel_distance_meters" : 97.41281890869141, "spatial_relationship" : "AROUND_THE_CORNER", "types" : [ "establishment", "point_of_interest", "tourist_attraction", "travel_agency" ] }, { "display_name" : { "language_code" : "en", "text" : "Axis Bank Branch" }, "straight_line_distance_meters" : 102.3495178222656, "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4", "travel_distance_meters" : 330.8566284179688, "spatial_relationship" : "DOWN_THE_ROAD", "types" : [ "bank", "establishment", "finance", "point_of_interest" ] } ] } }
Có 2 mảng trong mỗi đối tượng address_descriptor
: landmarks
và
areas
. Mảng landmarks
chứa tối đa 5 kết quả được xếp hạng theo thứ tự
mức độ phù hợp bằng cách xét đến độ gần với toạ độ được yêu cầu,
mức độ phổ biến của địa danh và chế độ hiển thị của địa danh đó. Mỗi kết quả về mốc chứa
các giá trị sau:
place_id
là mã địa điểm của kết quả về địa danh. Xem mã địa điểm tổng quan.display_name
là tên hiển thị của mốc, chứalanguage_code
vàtext
.straight_line_distance_meters
là khoảng cách từ điểm này đến điểm khác (tính bằng mét) giữa toạ độ đầu vào và kết quả của điểm mốc.travel_distance_meters
là khoảng cách tính bằng mét khi người đi qua mạng lưới đường (bỏ qua các quy định hạn chế về đường) giữa toạ độ đầu vào và kết quả về điểm mốc.spatial_relationship
là mối quan hệ ước tính giữa toạ độ đầu vào và kết quả của điểm mốc:"NEAR"
là mối quan hệ mặc định khi không có điều nào sau đây áp dụng."WITHIN"
khi toạ độ đầu vào nằm trong giới hạn của cấu trúc liên kết với mốc."BESIDE"
khi toạ độ đầu vào nằm ngay cạnh điểm truy cập của mốc hoặc điểm mốc."ACROSS_THE_ROAD"
khi toạ độ đầu vào đối diện trực tiếp với điểm mốc ở phía bên kia của tuyến đường."DOWN_THE_ROAD"
khi toạ độ đầu vào dọc theo cùng một tuyến đường với điểm mốc, nhưng không phải là"BESIDES"
hoặc"ACROSS_THE_ROAD"
."AROUND_THE_CORNER"
khi toạ độ đầu vào dọc theo một tuyến đường vuông góc là điểm mốc (bị hạn chế một lượt)."BEHIND"
khi toạ độ đầu vào gần với điểm mốc về mặt không gian, nhưng cách xa điểm truy cập.types
là Place types (Loại địa điểm) của mốc.
Đối tượng areas
chứa tối đa 3 phản hồi và tự giới hạn ở những nơi mà
đại diện cho các khu vực nhỏ như các vùng lân cận, các địa phương và khu vực lớn
phức tạp. Các khu vực có chứa toạ độ được yêu cầu được liệt kê trước và
theo thứ tự từ nhỏ đến lớn. Mỗi kết quả areas
đều chứa nội dung sau
giá trị:
place_id
là mã địa điểm của kết quả về khu vực. Xem mã địa điểm tổng quan.display_name
là tên hiển thị của khu vực, bao gồmlanguage_code
vàtext
.containment
là mối quan hệ ngăn chặn ước tính giữa toạ độ đầu vào và kết quả theo khu vực:"NEAR"
là mối quan hệ mặc định khi không có điều nào sau đây áp dụng."WITHIN"
khi toạ độ đầu vào gần với tâm của khu vực."OUTSKIRTS"
khi toạ độ đầu vào gần với cạnh của khu vực.
Phạm vi áp dụng từ khoá mô tả địa chỉ
Tính năng này chỉ có trên một số quốc gia khác.
Đây là tính năng Xem trước và chúng tôi rất mong nhận được ý kiến phản hồi của bạn. Vui lòng gửi email cho chúng tôi theo địa chỉ address-descriptors-feedback@google.com.
Đảo ngược mã hoá địa lý (Tra cứu địa chỉ)
Thuật ngữ mã hoá địa lý thường đề cập đến việc dịch dữ liệu mà con người có thể đọc được vào một vị trí trên bản đồ. Quá trình trò chuyện, dịch một vị trí trên bản đồ thành một địa chỉ con người có thể đọc được, được gọi là ngược mã hoá địa lý.
Thay vì cung cấp address
văn bản, hãy cung cấp một dấu phẩy được phân tách bằng dấu phẩy
cặp vĩ độ/kinh độ trong thông số location
.
Ví dụ sau đây mã hoá địa lý một giá trị vĩ độ/kinh độ và đặt bản đồ tại vị trí đó, hiển thị 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;
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;
Dùng thử mẫu
Lưu ý rằng trong ví dụ trước, chúng tôi đã hiển thị kết quả đầu tiên theo
đang chọn results[0]
. Bộ mã hoá địa lý đảo ngược thường trả về nhiều hơn
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
để đặt tên theo vị trí địa lý. Ví dụ: khi mã hoá địa lý một điểm trong
thành phố Chicago, thì đ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 (The United)
Tiểu bang). Tất cả đều là địa chỉ cho bộ mã hoá địa lý. Bộ mã hoá địa lý đảo ngược trả về tất cả
của những kết quả này.
Bộ mã hoá địa lý ngược khớp với các pháp nhân chính trị (quốc gia, tỉnh, thành phố và vùng lân cận), địa chỉ đường phố và mã bưu chính.
Dưới đây là ví dụ về danh sách địa chỉ mà truy vấn ở trên có thể trả về:
results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA" results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA" results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA" results[3].formatted_address: "Brooklyn, NY, USA" results[4].formatted_address: "New York, NY, USA" results[5].formatted_address: "Brooklyn, NY 11211, USA" results[6].formatted_address: "Kings County, NY, USA" results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA" results[8].formatted_address: "New York Metropolitan Area, USA" results[9].formatted_address: "New York, USA"
Các địa chỉ được trả về theo thứ tự từ tốt nhất đến ít trùng khớp nhất. 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ề các loại địa chỉ khác nhau, từ thông tin cụ thể nhất
địa chỉ đường phố đến các tổ chức chính trị ít cụ thể hơn như vùng lân cận,
thành phố, hạt, tiểu bang, v.v. Nếu bạn 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ý đảo không phải là một khoa học. Bộ mã hoá địa lý sẽ cố gắng tìm vị trí có thể định vị gần nhất trong phạm vi dung sai nhất định.
Truy xuất địa chỉ cho mã địa điểm
Cung cấp placeId
để tìm địa chỉ của một mã địa điểm nhất định. Chiến lược phát hành đĩa đơn
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
được trả về bởi
Roads API để tải
của một điểm cố định. Để biết thêm thông tin về mã địa điểm, hãy xem
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ỳ
các trường sau:
address
latLng
location
componentRestrictions
Ví dụ sau đây chấp nhận mã địa điểm, tìm địa chỉ tương ứng, và căn giữa bản đồ tại vị trí đó. Thao tác này cũng mở ra một cửa sổ thông tin hiển thị địa chỉ được định dạng của địa điểm có liên quan:
TypeScript
// Initialize the map. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 8, center: { lat: 40.72, lng: -73.96 }, } ); const geocoder = new google.maps.Geocoder(); const infowindow = new google.maps.InfoWindow(); (document.getElementById("submit") as HTMLElement).addEventListener( "click", () => { geocodePlaceId(geocoder, map, infowindow); } ); } // This function is called when the user clicks the UI button requesting // a geocode of a place ID. function geocodePlaceId( geocoder: google.maps.Geocoder, map: google.maps.Map, infowindow: google.maps.InfoWindow ) { const placeId = (document.getElementById("place-id") as HTMLInputElement) .value; geocoder .geocode({ placeId: placeId }) .then(({ results }) => { if (results[0]) { map.setZoom(11); map.setCenter(results[0].geometry.location); const marker = new google.maps.Marker({ map, position: results[0].geometry.location, }); infowindow.setContent(results[0].formatted_address); infowindow.open(map, marker); } else { window.alert("No results found"); } }) .catch((e) => window.alert("Geocoder failed due to: " + e)); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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;