Mã hoá địa lý ngược dịch một vị trí trên bản đồ thành đị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 Code của địa chỉ
- Thông tin chi tiết về địa chỉ
API này 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, thành phố, hạt 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 xác định vị trí ngược là yêu cầu HTTP GET. Bạn có thể chỉ định vị trí dưới dạng chuỗi không có cấu trúc:
https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE
Hoặc dưới dạng một tập hợp có cấu trúc gồm các toạ độ vĩ độ và kinh độ được biểu thị bằng các tham số truy vấn:
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE
Bạn thường sử dụng định dạng có cấu trúc khi xử lý các thành phần vị trí được thu thập trong một 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 đề như 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 chuỗi được phân tách bằng dấu phẩy của các toạ độ vĩ độ và kinh độ:
https://geocode.googleapis.com/v4beta/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/v4beta/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/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338 &key=API_KEY
Sử dụng OAuth để đưa ra yêu cầu
API Địa chỉ được mã hoá địa lý phiên bản 4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với API Mã hoá địa lý, bạn phải chỉ định phạm vi chính xác cho mã thông báo OAuth. API Mã hoá địa lý 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 điểm cuối của API Địa chỉ.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 điểm cuối của API Mã hoá địa lý. 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 phát hành chính thức, vì đây là phạm vi chung cho phép truy cập vào tất cả các điểm cuối.
Để 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
resultscủa các đối tượngGeocodeResultđại diện cho địa điểm.Trình dịch địa lý 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 vị trí địa lý. 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 biểu thị dưới dạng đị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ỉ" cho trình mã hoá địa lý. Bộ mã hoá địa lý đảo ngược 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
plusCodethuộc loạiPlusCodechứa Mã cộng 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 dưới 10 mét.
Đố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í bạn muốn có địa chỉ gần nhất và dễ đọc.
Thông số tùy chọn
languageCode
Ngôn ngữ dùng để trả về kết quả.
- Xem danh sách 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 sẽ cố gắng hết sức để cung cấp đị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 đó, lớp này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một tập lệnh 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ả địa chỉ khác sẽ được trả về bằng ngôn ngữ ưu tiên. Tất 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 nào bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên 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ề các kết quả đó. Trình mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ theo ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường 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ã vùng dưới dạng giá trị mã CLDR gồm hai ký tự. Không có giá trị mặc định. Hầu hết mã CLDR giống với mã ISO 3166-1.
Khi mã hoá địa lý một địa chỉ, chuyển tiếp mã hoá địa lý, tham số này có thể ảnh hưởng nhưng không hoàn toàn hạn chế kết quả của dịch vụ đối với khu vự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ể sử 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, như được xác định bởi
Granularity. Nếu bạn chỉ định nhiều thông sốgranularity, API sẽ trả về tất cả địa chỉ khớp với bất kỳ mức độ chi tiết nào.Tham số
granularitykhông hạn chế việc tìm kiếm ở mức độ chi tiết về vị trí đã chỉ định. Thay vào đó,granularityđóng vai trò là bộ lọc sau khi tìm kiếm. API sẽ 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 mức độ chi tiết về vị trí đã chỉ định.Nếu bạn chỉ định cả
typesvàgranularity, thì API sẽ chỉ trả về những kết quả khớp với cả hai. Ví dụ:https://geocode.googleapis.com/v4beta/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 tham số truy vấn riêng biệt. Nếu bạn chỉ định nhiều tham số
types, API sẽ trả về tất cả địa chỉ khớp với bất kỳ loại nào.Tham số
typeskhông hạn chế việc tìm kiếm ở(các) loại địa chỉ đã chỉ định. Thay vào đó,typesđóng vai trò là bộ lọc sau khi tìm kiếm. API sẽ 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àgranularity, thì API sẽ chỉ trả về những kết quả khớp với cả hai. Ví dụ:https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2
&types=locality &key=API_KEY Các giá trị sau được hỗ trợ:
Loại địa chỉ và loại thành phần địa chỉ
Mảng
typestrong phần nội dungGeocodeResultcủa phản hồi cho biết loại địa chỉ. Ví dụ về loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc thực thể chính trị. Mảngtypestrong trườngAddressComponentscủa nội dungGeocodeResultcho 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 loại
politicalvàlocality.Các loại sau đây được hỗ trợ và trả về trong cả kiểu địa chỉ và mảng kiểu thành phần địa chỉ:
Loại địa chỉ Mô tả street_addressĐịa chỉ đường phố chính xác. routeMột tuyến đường được đặt tên (chẳng hạn như "US 101"). intersectionMột giao lộ chính, thường là của hai con đường chính. politicalMột thực thể chính trị. Loại này thường cho biết một đa giác của một số cơ quan hành chính dân sự. countryThực thể chính trị quốc gia và thường là loại thứ tự cao nhất do Trình định vị địa lý trả về. administrative_area_level_1Một pháp nhân dân sự cấp một bên 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. 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 administrative_area_level_1sẽ khớp gần như hoàn toàn với các tiểu khu ISO 3166-2 và các danh sách khác được lưu hành rộng rãi; tuy nhiên, điều này không được đảm bảo vì kết quả mã hoá địa lý của chúng tôi dựa trên nhiều tín hiệu và dữ liệu vị trí.administrative_area_level_2Một pháp nhân dân sự cấp hai bên dưới cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là hạt. Không phải quốc gia nào cũng có các cấp hành chính này. administrative_area_level_3Một pháp nhân dân sự cấp ba bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này. administrative_area_level_4Một pháp nhân dân sự cấp thứ tư thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này. administrative_area_level_5Một pháp nhân dân sự cấp thứ năm bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này. administrative_area_level_6Một pháp nhân dân sự cấp thứ sáu, thấp hơn cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này. administrative_area_level_7Một pháp nhân dân sự cấp thứ bảy bên dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính cấp dưới. Không phải quốc gia nào cũng có các cấp hành chính này. colloquial_areaTên thay thế thường dùng cho thực thể. localityMột pháp nhân chính trị là thành phố hoặc thị trấn được hợp nhất. sublocalityMột pháp nhân dân sự cấp một bên dưới một địa phương. Một số vị trí có thể nhận được một trong các loại bổ sung: sublocality_level_1đếnsublocality_level_5. Mỗi cấp địa phương phụ là một thực thể dân sự. Số lớn hơn cho biết khu vực địa lý nhỏ hơn.neighborhoodMột khu vực lân cận được đặt tên. premiseMột vị trí được đặt tên, thường là một toà nhà hoặc một tập hợp các toà nhà có tên chung. subpremiseMột thực thể có thể định địa chỉ ở cấp dưới cơ sở, chẳng hạn như căn hộ, phòng hoặc căn hộ. plus_codeTham chiếu vị trí được mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng plus code để thay thế địa chỉ đường phố ở những nơi không có địa chỉ đường phố (những nơi không có số nhà hoặc tên đường). Hãy xem https://plus.codes để biết thông tin chi tiết. postal_codeMã bưu chính dùng để ghi địa chỉ thư bưu chính trong quốc gia. natural_featureMột đặc điểm tự nhiên nổi bật. airportSân bay. parkMột công viên được đặt tên. point_of_interestMột địa điểm yêu thích được đặt tên. Thông thường, những "điểm yêu thích" này là các thực thể nổi bật tại địa phương và không dễ dàng phù hợp với một danh mục khác, chẳng hạn như "Toà nhà Empire State" hoặc "Tháp Eiffel". Danh sách loại trống cho biết không có loại nào được biết cho thành phần địa chỉ cụ thể (ví dụ: Lieu-dit ở Pháp).