Mã hoá địa lý ngược chuyển đổi vị trí trên bản đồ thành một địa chỉ mà con người có thể đọc được. Bạn biểu thị vị trí trên bản đồ bằng toạ độ vĩ độ và kinh độ của vị trí đó.
Khi bạn mã hoá địa lý ngược một vị trí, phản hồi sẽ chứa:
- Mã địa điểm của địa chỉ
- Plus Codes của địa chỉ
- Thông tin về địa chỉ
API này trả về nhiều loại địa chỉ, từ địa chỉ đường cụ thể nhất đến các thực thể chính trị ít cụ thể hơn, chẳng hạn như khu dân cư, thành phố, quận và tiểu bang. Địa chỉ chính xác nhất thường là kết quả đầu tiên. Nếu bạn muốn so khớp một loại địa chỉ cụ thể, hãy sử dụng tham số types.
Yêu cầu mã hoá địa lý ngược
Yêu cầu mã hoá địa lý ngược là một yêu cầu GET HTTP. Bạn có thể chỉ định vị trí dưới dạng một chuỗi không có cấu trúc:
https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE
Hoặc dưới dạng một tập hợp có cấu trúc gồm toạ độ vĩ độ và kinh độ được biểu thị bằng các tham số truy vấn:
https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE
Bạn thường dùng định dạng có cấu trúc khi xử lý các thành phần vị trí được ghi lại trong biểu mẫu HTML.
Truyền tất cả các tham số khác dưới dạng tham số URL hoặc đối với các tham số như khoá API hoặc mặt nạ trường, trong tiêu đề dưới dạng một phần của yêu cầu GET. Ví dụ:
Truyền một chuỗi vị trí không có cấu trúc
Vị trí không có cấu trúc là vị trí được định dạng dưới dạng một chuỗi gồm các toạ độ vĩ độ và kinh độ được phân tách bằng dấu phẩy:
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY
Hoặc trong lệnh curl:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
Truyền một vị trí có cấu trúc
Chỉ định vị trí có cấu trúc bằng cách sử dụng tham số truy vấn location, thuộc loại LatLng.
Đối tượng LatLng cho phép bạn chỉ định vĩ độ và kinh độ dưới dạng các tham số truy vấn riêng biệt:
https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338 &key=API_KEY
Sử dụng OAuth để đưa ra yêu cầu
Geocoding API phiên bản 4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với Geocoding API, bạn phải chỉ định đúng phạm vi cho mã thông báo OAuth. Geocoding API hỗ trợ các phạm vi sau để sử dụng với tính năng mã hoá địa lý ngược:
https://www.googleapis.com/auth/maps-platform.geocode– Sử dụng với tất cả các phương thức Geocoding API.https://www.googleapis.com/auth/maps-platform.geocode.location– Chỉ sử dụng vớiGeocodeLocationđể mã hoá địa lý ngược.
Ngoài ra, bạn có thể sử dụng phạm vi https://www.googleapis.com/auth/cloud-platform chung cho tất cả các phương thức Geocoding API. Phạm vi đó hữu ích trong quá trình phát triển nhưng không hữu ích trong quá trình sản xuất, vì đây là một phạm vi chung cho phép truy cập vào tất cả các phương thức.
Để biết thêm thông tin và ví dụ, hãy xem phần Sử dụng OAuth.
Phản hồi mã hoá địa lý ngược
Tính năng mã hoá địa lý ngược trả về một đối tượng GeocodeLocationResponse chứa:
-
Mảng
resultsgồm các đối tượngGeocodeResultđại diện cho địa điểm.Phản hồi của Geocoding API bao gồm các mảng
typesở 2 vị trí chính trongGeocodeResult:GeocodeResult.types: Mảng này cho biết(các) loại kết quả tổng thể. Các giá trị có thể được lấy từ Bảng A và Bảng B trên trang Loại địa điểm (Mới).GeocodeResult.addressComponents[].types: Mỗi thành phần địa chỉ đều có một mảngtypescho biết loại của phần địa chỉ cụ thể đó. Các giá trị này được lấy từ bảng Loại địa chỉ và loại thành phần địa chỉ trên trang Loại địa điểm (Mới).
Trình địa lý hoá ngược trả về nhiều kết quả trong mảng
results. Kết quả không chỉ là địa chỉ bưu chính mà còn là mọi cách để đặt tên cho một vị trí theo địa lý. Ví dụ: khi mã hoá địa lý một điểm ở thành phố Chicago, điểm được mã hoá địa lý có thể được biểu thị dưới dạng địa chỉ đường phố, dưới dạng thành phố (Chicago), dưới dạng tiểu bang (Illinois) hoặc dưới dạng quốc gia (Hoa Kỳ). Tất cả đều là "địa chỉ" đối với trình mã hoá địa lý. Trình chuyển đổi địa lý ngược sẽ trả về bất kỳ loại nào trong số này dưới dạng kết quả hợp lệ. -
Trường
plusCode, thuộc loạiPlusCode, chứa Plus Code gần đúng nhất với vĩ độ và kinh độ trong yêu cầu. Ngoài ra, mỗi phần tử của mảngresultsđều chứa một Mã Plus. Khoảng cách giữa Mã cộng đã giải mã và điểm yêu cầu là dưới 10 mét.Lưu ý: API này không phải lúc nào cũng trả về Plus Code.
Đối tượng JSON hoàn chỉnh có dạng:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU", "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU", "location": { "latitude": 37.422588300000008, "longitude": -122.0846489 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421239319708512, "longitude": -122.0859978802915 }, "high": { "latitude": 37.423937280291511, "longitude": -122.08329991970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCW83+PM", "compoundCode": "CW83+PM Mountain View, CA, USA" } }, { "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw", "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "location": { "latitude": 37.4220541, "longitude": -122.08532419999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4207051197085, "longitude": -122.08667318029148 }, "high": { "latitude": 37.423403080291493, "longitude": -122.08397521970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "establishment", "point_of_interest" ], "plusCode": { "globalCode": "849VCWC7+RV", "compoundCode": "CWC7+RV Mountain View, CA, USA" } }, ... ], "plusCode": { "globalCode": "849VCWF8+24H", "compoundCode": "CWF8+24H Mountain View, CA, USA" } }
Thông số bắt buộc
vị trí
Toạ độ vĩ độ và kinh độ chỉ định vị trí mà bạn muốn có địa chỉ gần nhất, dễ đọc.
Thông số tùy chọn
languageCode
Ngôn ngữ mà bạn muốn nhận kết quả.
- Xem danh sách các ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
-
Nếu bạn không cung cấp
languageCode, API sẽ mặc định làen. Nếu bạn chỉ định một mã ngôn ngữ không hợp lệ, API sẽ trả về lỗiINVALID_ARGUMENT. - API này cố gắng cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được. Để đạt được mục tiêu đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
- Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả trùng khớp gần nhất.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác.
regionCode
Mã khu vực dưới dạng giá trị mã CLDR gồm 2 ký tự. Không có giá trị mặc định. Hầu hết mã CLDR đều giống với mã ISO 3166-1.
Khi mã hoá địa lý một địa chỉ, mã hoá địa lý xuôi, tham số này có thể ảnh hưởng nhưng không hạn chế hoàn toàn kết quả từ dịch vụ đối với khu vực được chỉ định. Khi mã hoá địa lý một vị trí hoặc một địa điểm, mã hoá địa lý ngược hoặc mã hoá địa lý địa điểm, bạn có thể dùng tham số này để định dạng địa chỉ. Trong mọi trường hợp, tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
độ chi tiết
Một hoặc nhiều mức độ chi tiết về vị trí, được chỉ định dưới dạng các tham số truy vấn riêng biệt, theo định nghĩa của
Granularity. Nếu bạn chỉ định nhiều tham sốgranularity, API sẽ trả về tất cả các địa chỉ khớp với bất kỳ độ chi tiết nào.Tham số
granularitykhông hạn chế phạm vi tìm kiếm ở mức độ chi tiết của vị trí được chỉ định. Thay vào đó,granularityhoạt động như một bộ lọc sau khi tìm kiếm. API tìm nạp tất cả kết quả cholocationđã chỉ định, sau đó loại bỏ những kết quả không khớp với độ chi tiết vị trí đã chỉ định.Nếu bạn chỉ định cả
typesvàgranularitythì API chỉ trả về những kết quả khớp với cả hai. Ví dụ:https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP
&granularity=GEOMETRIC_CENTER &key=API_KEY loại
Một hoặc nhiều loại địa chỉ, được chỉ định dưới dạng các tham số truy vấn riêng biệt. Các giá trị có thể được lấy từ bảng Các loại địa chỉ và các loại thành phần địa chỉ trên trang Loại địa điểm (Mới). Nếu bạn chỉ định nhiều tham số
types, API sẽ trả về tất cả các địa chỉ khớp với bất kỳ loại nào.Tham số
typeskhông hạn chế phạm vi tìm kiếm đối với(các) loại địa chỉ được chỉ định. Thay vào đó,typeshoạt động như một bộ lọc sau khi tìm kiếm. API này tìm nạp tất cả kết quả cho vị trí đã chỉ định, sau đó loại bỏ những kết quả không khớp với(các) loại địa chỉ đã chỉ định.Nếu bạn chỉ định cả
typesvàgranularitythì API sẽ chỉ trả về những kết quả khớp với cả hai. Ví dụ:https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2
&types=locality &key=API_KEY -
FieldMask
Tạo một mặt nạ trường phản hồi để chỉ định các trường cần trả về trong phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tham số URL
$fieldshoặcfields, hoặc bằng cách sử dụng tiêu đề HTTPX-Goog-FieldMask. Ví dụ: yêu cầu dưới đây sẽ chỉ trả về các trườngplaceIDcủa phản hồi.curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
{ "results": [ { "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE" }, { "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g" }, { "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k" }, { "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8" }, ... ] }
Xem phần Chọn các trường cần trả về để biết thêm thông tin chi tiết.