Trang này được dịch bởi Cloud Translation API.

Yêu cầu và phản hồi 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 làm ngược lại, chuyển đổi một vị trí trên bản đồ thành địa chỉ mà con người có thể đọc được, được gọi là mã hoá địa lý ngược.

Yêu cầu mã hoá địa lý ngược

Thông số bắt buộc

latlng – Toạ độ vĩ độ và kinh độ chỉ định vị trí mà bạn muốn có địa chỉ gần nhất và dễ đọc.
key – Khoá API của ứng dụng. Khoá này xác định ứng dụng của bạn cho mục đích quản lý hạn mức. Tìm hiểu cách lấy khoá.

Thông số tùy chọn

Đây là các tham số không bắt buộc mà bạn có thể đưa vào yêu cầu gán địa lý đảo ngược:

language – 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 language, trình định vị địa lý sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language hoặc ngôn ngữ gốc của miền gửi yêu cầu.
- Trình dịch địa lý cố gắng 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 sẽ 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 đượ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, thì trình dịch địa lý sẽ sử dụng tên trùng khớp gần nhất.
region – Mã vùng, được chỉ định dưới dạng giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Tham số này cũng có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
result_type – Bộ lọc của một hoặc nhiều loại địa chỉ, được phân tách bằng dấu gạch chéo (|). Nếu tham số chứa nhiều loại địa chỉ, API sẽ trả về tất cả địa chỉ khớp với bất kỳ loại nào. Lưu ý về quá trình xử lý: Tham số result_type không hạn chế việc tìm kiếm ở(các) loại địa chỉ đã chỉ định. Thay vào đó, result_type đóng vai trò là bộ lọc sau khi tìm kiếm: API tìm nạp tất cả kết quả cho latlng đã 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. Các giá trị sau đây được hỗ trợ:
- street_address cho biết địa chỉ đường phố chính xác.
- route cho biết một tuyến đường được đặt tên (chẳng hạn như "US 101").
- intersection cho biết một giao lộ chính, thường là của hai đường chính.
- political cho biết một thực thể chính trị. Thông thường, loại này cho biết một đa giác của một số cơ quan hành chính dân sự.
- country cho biết thực thể chính trị quốc gia và thường là loại thứ tự cao nhất do Trình định mã địa lý trả về.
- administrative_area_level_1 cho biết một thực thể dân sự cấp một bên dưới cấp quốc gia. Tại Hoa Kỳ, các cấp quản lý này là tiểu bang. Không phải quốc gia nào cũng có các cấp quản lý này. Trong hầu hết các trường hợp, tên ngắn của administrative_area_level_1 sẽ khớp gần như hoàn toàn với các tiểu khu theo 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_2 cho biết một thực thể dân sự cấp hai thấp hơn 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 quản lý này.
- administrative_area_level_3 cho biết một thực thể dân sự cấp ba 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_4 cho biết một thực thể dân sự bậc bốn 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_5 cho biết một thực thể 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_6 cho biết một thực thể dân sự bậc sáu 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_7 cho biết một thực thể dân sự bậc 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_area cho biết tên thay thế thường dùng cho thực thể.
- locality cho biết một thực thể chính trị của thành phố hoặc thị trấn được hợp nhất.
- sublocality cho biết một thực thể dân sự cấp một bên 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 đến sublocality_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.
- neighborhood cho biết một khu vực được đặt tên.
- premise cho biết mộ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.
- subpremise cho biết một thực thể có thể định địa chỉ bên dưới cấp cơ sở, chẳng hạn như căn hộ, phòng hoặc căn hộ.
- plus_code cho biết một tệp tham 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 cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố (những nơi không đánh số nhà hoặc không đặt tên đường). Hãy xem https://plus.codes để biết thông tin chi tiết.
- postal_code cho biết mã bưu chính dùng để gửi thư qua đường bưu chính 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ê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 "đ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ư "Tòa nhà Empire State" hoặc "Tháp Eiffel".
location_type – Bộ lọc của một hoặc nhiều loại vị trí, được phân tách bằng dấu gạch chéo (|). Nếu thông số chứa nhiều loại vị trí, thì API sẽ trả về tất cả địa chỉ khớp với bất kỳ loại nào. Lưu ý về quá trình xử lý: Tham số location_type không hạn chế việc tìm kiếm ở các loại vị trí đã chỉ định. Thay vào đó, location_type đóng vai trò là bộ lọc sau khi tìm kiếm: API tìm nạp tất cả kết quả cho latlng đã chỉ định, sau đó loại bỏ những kết quả không khớp với các loại vị trí đã chỉ định. Những giá trị sau đây được hỗ trợ:
- "ROOFTOP" chỉ trả về những địa chỉ mà Google có thông tin vị trí chính xác đến độ chính xác của địa chỉ đường phố.
- "RANGE_INTERPOLATED" chỉ trả về các địa chỉ 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ư các giao lộ). Phạm vi nội suy thường cho biết rằng không có mã địa lý trên sân thượng cho địa chỉ đường phố.
- "GEOMETRIC_CENTER" chỉ trả về tâm hình học của một vị trí, chẳng hạn như một đường đa tuyến (ví dụ: một con đường) hoặc một đa giác (khu vực).
- "APPROXIMATE" chỉ trả về những địa chỉ được mô tả là gần đúng.
extra_computations – Sử dụng tham số này để chỉ định các tính năng bổ sung sau trong phản hồi:
- ADDRESS_DESCRIPTORS – Xem trình mô tả địa chỉ để biết thêm thông tin chi tiết.
- BUILDING_AND_ENTRANCES – Xem các lối vào và đường viền của toà nhà để biết thêm thông tin chi tiết.
Để bật nhiều tính năng trong số này cho cùng một yêu cầu API, hãy đưa tham số extra_computations vào yêu cầu cho từng tính năng, ví dụ:
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

Nếu có cả bộ lọc result_type và location_type, thì API chỉ trả về những kết quả khớp với cả giá trị result_type và location_type. Nếu không có giá trị bộ lọc nào được chấp nhận, API sẽ trả về ZERO_RESULTS.

Ví dụ về việc mã hoá địa lý ngược

Truy vấn sau đây chứa giá trị vĩ độ/kinh độ của một vị trí ở Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Lưu ý: Đảm bảo không có khoảng trắng giữa các giá trị vĩ độ và kinh độ khi được truyền vào tham số latlng.

Truy vấn trên trả về kết quả sau:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Xin lưu ý rằng trình dịch địa lý ngược đã trả về nhiều kết quả. Kết quả "formatted_address" không chỉ là địa chỉ bưu chính mà còn là mọi cách để đặt tên theo vị trí địa lý cho một vị trí. Ví dụ: khi mã hoá địa lý một điểm trong thành phố Chicago, điểm được mã hoá địa lý có thể được 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ý. Trình dịch địa lý 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ình dịch địa lý ngược so khớp các thực thể chính trị (quốc gia, tỉnh, thành phố và khu vực lân cận), địa chỉ đường phố và mã bưu chính.

Danh sách đầy đủ các giá trị formatted_address do truy vấn trước trả về được hiển thị bên dưới.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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ỉ càng chính xác thì kết quả càng nổi bật, như trong trường hợp này. Nếu bạn muốn so khớp một loại địa chỉ cụ thể, hãy xem phần bên dưới về cách giới hạn kết quả theo loại. Do đó, vị trí của các kết quả so với nhau có thể khác nhau.

Mã hoá địa lý ngược được lọc theo loại

Ví dụ sau đây lọc các địa chỉ được trả về để chỉ bao gồm những địa chỉ có loại vị trí là ROOFTOP và loại địa chỉ là street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Lưu ý: Các bộ lọc này chỉ hợp lệ cho tính năng truy vấn địa lý đảo ngược.

Phản hồi mã hoá địa lý ngược

Định dạng của phản hồi mã hoá địa lý ngược giống với phản hồi Mã hoá địa lý. Xem phần Phản hồi về việc tạo địa chỉ địa lý. Dưới đây là các mã trạng thái có thể có trong phản hồi dịch địa lý ngược.

Mã trạng thái của tính năng đảo ngược mã địa lý

Trường "status" trong đối tượng phản hồi Địa chỉ được mã hoá chứa trạng thái của yêu cầu và có thể chứa thông tin gỡ lỗi để giúp bạn theo dõi lý do khiến tính năng địa chỉ được mã hoá ngược không hoạt động. Trường "status" có thể chứa các giá trị sau:

"OK" cho biết không có lỗi nào xảy ra và ít nhất một địa chỉ đã được trả về.
"ZERO_RESULTS" cho biết việc mã hoá địa lý đảo ngược đã 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 trình mã hoá địa lý được truyền latlng ở một vị trí từ xa.
"OVER_QUERY_LIMIT" cho biết bạn đã vượt quá hạn mức.
"REQUEST_DENIED" cho biết yêu cầu đã bị từ chối. Có thể là do yêu cầu bao gồm tham số result_type hoặc location_type nhưng không bao gồm khoá API.
"INVALID_REQUEST" thường cho biết một trong những điều sau:
- Thiếu truy vấn (address, components hoặc latlng).
- Bạn đã cung cấp result_type hoặc location_type không hợp lệ.
"UNKNOWN_ERROR" cho biết 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.

Mã hoá địa lý ngược cho plus code

Trường plus_code trong phản hồi Địa chỉ được mã hoá địa lý chứa một mã cộng gần đúng nhất với vĩ độ và kinh độ được truy vấn. Ngoài ra, trong hầu hết trường hợp, mảng kết quả JSON chứa kết quả Địa chỉ đầy đủ với loại plus_code và địa chỉ chứa mã cộng. Khoảng cách giữa mã plus đã giải mã và điểm yêu cầu được đảm bảo là dưới 10 mét.