Yêu cầu và phản hồi mã hóa địa lý ngược (tra cứu địa chỉ)

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Thuật ngữ địa mã hoá thường dùng để chỉ việc chuyển đổi 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, tức là 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.

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, 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 địa lý mã hoá 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 mã hoá đị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ữ mẹ đẻ của miền mà từ đó yêu cầu được gửi.
    • Trình mã hoá địa lý 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 đó, API 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), đồng thời tuân thủ 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, thì trình mã hoá địa lý sẽ sử dụng kết quả trùng khớp gần nhất.
  • region – Mã khu vực, được chỉ định làm giá trị gồm 2 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 gồm một hoặc nhiều loại địa chỉ, được phân tách bằng dấu gạch dọc (|). 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ề quy trình xử lý: Tham số result_type khô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 đó, result_type hoạ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ả 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 được hỗ trợ:

    Loại địa chỉ và loại thành phần địa chỉ

    Mảng types trong nội dung GeocodeResult trong phản hồi cho biết loại địa chỉ. Ví dụ về các loại địa chỉ bao gồm địa chỉ đường phố, quốc gia hoặc thực thể chính trị. Mảng types trong trường AddressComponents của nội dung GeocodeResult cho 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 các loại political và locality.

    Các loại sau đây được hỗ trợ và trả về trong cả mảng loại địa chỉ và loại thành phần địa chỉ:

    Loại địa chỉ Mô tả
    street_address Địa chỉ đường phố chính xác.
    route Một tuyến đường có tên (chẳng hạn như "US 101").
    intersection Một giao lộ lớn, thường là nơi giao nhau của hai con đường lớn.
    political Một pháp nhân 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 Thực thể chính trị quốc gia và thường là loại thứ tự cao nhất do Trình mã hoá địa lý trả về.
    administrative_area_level_1 Một khu vực hành chính cấp một 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_1 sẽ gần giống với các phân vùng 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 Một thực thể dân sự cấp hai 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_3 Một thực thể dân sự cấp thứ ba dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. 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 Một thực thể dân sự cấp thứ tư dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. 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 Một thực thể dân sự cấp thứ năm dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. 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 Một thực thể dân sự cấp thứ sáu dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. 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 Một thực thể dân sự cấp thứ bảy dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Không phải quốc gia nào cũng có các cấp hành chính này.
    colloquial_area Tên thay thế thường dùng cho thực thể.
    locality Một pháp nhân chính trị là thành phố hoặc thị trấn hợp nhất.
    sublocality Một khu vực hành chính 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 độ tiểu khu là một thực thể dân sự. Số càng lớn thì khu vực địa lý càng nhỏ.
    neighborhood Một khu phố có tên.
    premise Một vị trí có tên, thường là một toà nhà hoặc một nhóm toà nhà có tên chung.
    subpremise Một thực thể có thể định địa chỉ ở dưới cấp cơ sở, chẳng hạn như căn hộ, phòng hoặc dãy phòng.
    plus_code Một thông tin tham chiếu được mã hoá về vị trí, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể dùng mã cộng thay cho địa chỉ đường phố ở những nơi không có địa chỉ đường phố (nơi các toà nhà không được đánh số hoặc đường phố không có tên). Hãy xem https://plus.codes để biết thông tin chi tiết.
    postal_code Mã bưu chính được dùng để gửi thư bưu chính trong quốc gia.
    natural_feature Một đối tượng tự nhiên nổi bật.
    airport Một sân bay.
    park Một công viên có tên.
    point_of_interest Một địa điểm yêu thích có tên. Thông thường, những "POI" này là các thực thể nổi bật tại địa phương, 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 trống các loại cho biết không có loại nào đã biết cho thành phần địa chỉ cụ thể (ví dụ: Lieu-dit ở Pháp).

  • location_type – Bộ lọc gồm một hoặc nhiều loại vị trí, được phân tách bằng dấu gạch dọc (|). Nếu tham số chứa nhiều loại vị trí, API sẽ trả về tất cả các địa chỉ khớp với bất kỳ loại nào. Lưu ý về quy trình xử lý: Tham số location_type không hạn chế phạm vi tìm kiếm đối với các loại vị trí được chỉ định. Thay vào đó, location_type hoạ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ả 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 từng địa chỉ đường phố.
    • "RANGE_INTERPOLATED" chỉ trả về những địa chỉ phản ánh một giá trị ước chừng (thường là trên đường) được suy đoán giữa 2 đ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 mã địa lý trên tầng thượng không có sẵn cho một đị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ư đường nhiều đường (ví dụ: đường phố) hoặc đa giác (khu vực).
    • "APPROXIMATE" chỉ trả về những địa chỉ được xác định là địa chỉ ước chừng.
  • extra_computations – Sử dụng tham số này để chỉ định các tính năng bổ sung sau đây trong phản hồi: Để bật nhiều tính năng trong số này cho cùng một yêu cầu API, hãy thêm 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ề mã hoá địa lý ngược

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

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

Truy vấn trên sẽ 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 địa mã hoá 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 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 chỉ thành toạ độ đị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ình mã hoá địa lý ngược sẽ so khớp các thực thể chính trị (quốc gia, tỉnh, thành phố và khu dân cư), địa chỉ đường phố và mã bưu chính.

Sau đây là danh sách đầy đủ các giá trị formatted_address do 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 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ỉ càng chính xác thì 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 một loại địa chỉ cụ thể, hãy xem phần bên dưới về hạn chế kết quả theo loại. Vì lý do này, 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ỉ có hiệu lực đối với tính năng mã hoá địa lý 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 hồi về mã hoá địa lý. Dưới đây là các mã trạng thái có thể có trong phản hồi về tính năng địa lý mã hoá ngược.

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

Trường "status" trong đối tượng phản hồi Geocoding 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 lý 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 quá trình địa lý hoá 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 một 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 có tham số result_type hoặc location_type nhưng không có 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 yêu cầu không xử lý được 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 Geocoding chứa mã cộng gần đúng nhất với vĩ độ và kinh độ được truy vấn. Ngoài ra, mảng kết quả JSON trong hầu hết các trường hợp đều chứa một kết quả Địa lý mã hoá đầy đủ có loại plus_code và một địa chỉ chứa mã cộng. Khoảng cách giữa mã cộng đã giải mã và điểm yêu cầu chắc chắn sẽ dưới 10 mét.