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 dùng để chỉ 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 thực hiện ngược lạ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.

Đảo ngược yêu cầu mã hoá địa lý

Thông số bắt buộc

latlng – Vĩ độ và kinh độ xác định vị trí mà bạn muốn có địa chỉ gần nhất mà con người có thể đọc được.
key — Khoá API cho ứng dụng của bạn. 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 mã hoá địa lý ngược:

language – Ngôn ngữ mà hệ thống sử 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ể không đầy đủ.
- Nếu bạn không cung cấp language, thì bộ mã hoá địa lý sẽ cố gắng sử dụng ngôn ngữ ưu tiên như đã chỉ định trong tiêu đề Accept-Language hoặc ngôn ngữ gốc của miền mà yêu cầu được gửi đi.
- Bộ mã hoá địa lý 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 có thể đọc được. Để đạt được mục tiêu đó, công cụ này trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang tập lệnh mà người dùng có thể đọc nếu cần, qua đó quan sát ngôn ngữ ưu tiên. Tất cả các địa chỉ khác sẽ đượ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 một tên không được cung cấp bằng ngôn ngữ ưu tiên, thì bộ mã hoá địa lý sẽ sử dụng kết quả khớp gần nhất.
region – Mã vùng, được chỉ định là ccTLD (miền cấp cao nhất) với giá trị gồm hai ký tự. Theo luật hiện hành, tham số này cũng có thể ảnh hưởng đến kết quả.
result_type – Bộ lọc gồm một hoặc nhiều loại địa chỉ, được phân tách bằng dấu gạch đứng (|). Nếu tham số chứa nhiều loại địa chỉ, thì API sẽ trả về tất cả địa chỉ khớp với bất kỳ loại nào trong số đó. Lưu ý về cách xử lý: Tham số result_type không restrict hoạt động tìm kiếm theo(các) loại địa chỉ đã chỉ định. Thay vào đó, result_type đóng vai trò như một bộ lọc sau khi tìm kiếm: API tìm nạp mọi kết quả cho latlng được 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 đượ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ên (chẳng hạn như "US 101").
- intersection biểu thị một giao lộ chính, thường là hai 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à thường là loại đơn đặt hàng cao nhất mà Bộ mã hoá địa lý trả về.
- administrative_area_level_1 cho biết có pháp nhân dân sự thứ nhất ở cấp thấp hơn cấp quốc gia. Tại Hoa Kỳ, những cấp hành chính này là các tiểu bang. Không phải quốc gia nào cũng thể hiện các cấp hành chính này. Trong hầu hết các trường hợp, tên rút nhập Hành chính
- administrative_area_level_2 cho biết một pháp nhân dân sự cấp hai ở cấp thấp hơn cấp quốc gia. Tại Hoa Kỳ, những cấp hành chính này là các hạt. 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_3 cho biết có pháp nhân dân sự cấp thứ ba ở cấp thấp hơn 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 cho biết có pháp nhân dân sự cấp thứ tư ở cấp thấp hơn 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 cho biết một pháp nhân dân sự cấp 5 ở cấp thấp hơn 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 cho biết một pháp nhân dân sự cấp 6 thấp hơn 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 cho biết một pháp nhân dân sự cấp 7 ở cấp thấp hơn 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 tên thay thế thường dùng cho thực thể.
- locality cho biết một pháp nhân chính trị đã được thành lập hoặc hợp tác với một thành phố hoặc thị trấn.
- sublocality cho biết một pháp nhân dân sự cấp cao nhất thuộc 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 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 biểu thị vùng lân cận đượ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 tập hợp các toà nhà cùng tên
- subpremise cho biết một thực thể bậc nhất bên dưới một vị trí đã đặt tên, thường là một toà nhà đơn lẻ trong tập hợp các toà nhà có cùng tên
- plus_code cho biết một tham chiếu vị trí được mã hoá, lấy từ vĩ độ và kinh độ. Mã Cộng có thể được dùng để thay thế cho địa chỉ đường phố ở những vị trí không tồn tại chúng (nơi toà nhà không được đánh số hoặc đường phố không được đặt tên). Hãy truy cập vào https://plus.codes để biết chi tiết.
- postal_code cho biết mã bưu chính dùng để giải quyết thư bưu chính 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à các thực thể địa phương 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".
location_type – Bộ lọc gồm một hoặc nhiều loại vị trí, phân tách bằng dấu gạch đứng (|). Nếu tham 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 trong số đó. Lưu ý về việc xử lý: Thông số location_type không restrict hoạt động tìm kiếm theo các loại vị trí được chỉ định. Thay vào đó, location_type đóng vai trò như một bộ lọc sau khi tìm kiếm: API tìm nạp mọi kết quả cho latlng được chỉ định, sau đó loại bỏ những kết quả không khớp với loại vị trí đã chỉ định. Các giá trị sau được hỗ trợ:
- "ROOFTOP" chỉ trả về các đị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 giá trị gần đúng (thường trên đường) được nội suy giữa hai điểm chính xác (chẳng hạn như giao lộ). Phạm vi nội suy thường cho biết rằng không có mã địa lý trên mái nhà cho địa chỉ đường phố.
- "GEOMETRIC_CENTER" chỉ trả về các tâm hình học của một vị trí, chẳng hạn như một hình nhiều đường (ví dụ: một đường phố) hoặc một đa giác (khu vực).
- "APPROXIMATE" chỉ trả về các địa chỉ được mô tả là gần đúng.
extra_computations – Giá trị duy nhất được phép sử dụng cho tham số này là ADDRESS_DESCRIPTORS. Xem phần mô tả địa chỉ để biết thêm chi tiết.

Nếu cả hai bộ lọc result_type và location_type đều có mặt, thì API sẽ 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ề mã hoá địa lý ngược

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

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

Lưu ý: Hãy đảm bảo rằng không có khoảng trống nào giữa các giá trị vĩ độ và kinh độ khi được truyền vào thông 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> ...

Lưu ý rằng bộ mã hoá địa lý đảo 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à cách đặt tên đị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ố, như thành phố (Chicago), tiểu bang (Illinois) hoặc một quốc gia (Hoa Kỳ). Tất cả đều là "địa chỉ" cho bộ 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ệ.

Bộ mã hoá địa lý đảo 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à danh sách đầy đủ các giá trị formatted_address mà truy vấn trước đó trả về.

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

Đảo ngược mã hoá địa lý được lọc theo loại

Ví dụ sau đây sẽ 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ệ để mã hoá địa lý ngược.

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

Định dạng của phản hồi mã hoá địa lý ngược giống như phản hồi Mã hoá địa lý. Hãy xem mục Phản hồi mã hoá địa lý. Dưới đây là các mã trạng thái có thể có trong phản hồi mã hoá địa lý đảo ngược.

Đảo ngược mã trạng thái mã hoá địa lý

Trường "status" trong đối tượng phản hồi Mã hoá địa lý 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 mã hoá địa lý 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 quá trình mã hoá địa lý 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 bộ 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 có khoá API.
"INVALID_REQUEST" thường biểu thị một trong những điều sau:
- Truy vấn (address, components hoặc latlng) bị thiếu.
- 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.

Đảo ngược mã cộng

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