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ữ 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, tức là dịch 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

Tham 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, con người có thể đọc đượ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

Sau đâ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ữ để 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, thì 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ữ gốc của miền mà yêu cầu được gửi từ đó.
    • 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 đề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 hệ chữ viết 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 đượ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 bằng ngôn ngữ ưu tiên, thì bộ mã hoá địa lý sẽ sử dụng tên phù hợp nhất.
  • region — Mã khu vực, đượ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 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. Lưu ý về việc xử lý: Tham số result_type không hạn chế việc tìm kiếm đối với(các) loại địa chỉ được 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 được chỉ định, sau đó loại bỏ những kết quả không khớp với(các) loại địa chỉ được chỉ định. API này hỗ trợ các giá trị sau:

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

    Mảng types trong phần nội dung GeocodeResult của 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 pháp nhân chính trị. Mảng types trong trường AddressComponents của phần 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à mảng 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 Tuyến đường có tên (chẳng hạn như "US 101").
    intersection Giao lộ lớn, thường là của hai đường chính.
    political Một pháp nhân chính trị. Thông thường, loại này cho biế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 mà Bộ mã hoá địa lý trả về.
    administrative_area_level_1 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. Chỉ một số quốc gia 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ẽ khớp gần đúng với các phân khu ISO 3166-2 và các danh sách được lưu hành rộng rãi khác; 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 Khu vực hành chính 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. Chỉ một số quốc gia có các cấp hành chính này.
    administrative_area_level_3 Khu vực hành chính cấp ba dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này.
    administrative_area_level_4 Khu vực hành chính cấp bốn dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính nhỏ. Chỉ một số quốc gia có các cấp hành chính này.
    administrative_area_level_5 Khu vực hành chính cấp 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ỏ. Chỉ một số quốc gia có các cấp hành chính này.
    administrative_area_level_6 Khu vực hành chính cấp 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ỏ. Chỉ một số quốc gia có các cấp hành chính này.
    administrative_area_level_7 Khu vực hành chính cấp 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ỏ. Chỉ một số quốc gia có các cấp hành chính này.
    colloquial_area Tên thay thế thường dùng cho pháp nhân.
    locality Một pháp nhân chính trị của thành phố hoặc thị trấn được thành lập hợp pháp.
    sublocality Khu vực hành chính cấp một dưới cấp đị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 đến sublocality_level_5. Mỗi cấp địa phương phụ là một thực thể dân sự. Số càng lớn thì khu vực địa lý càng nhỏ.
    neighborhood Khu vực lân cận có tên.
    premise Một vị trí có 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 Một thực thể có địa chỉ bên dưới cấp cơ sở, chẳng hạn như căn hộ, đơn vị hoặc phòng.
    plus_code Một thông tin tham chiếu vị trí được mã hoá, bắt nguồn từ vĩ độ và kinh độ. Bạn có thể sử dụng Plus Codes để thay thế cho địa chỉ đường phố ở những nơi không có địa chỉ (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 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 Sân bay.
    park 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 "địa điểm yêu thích" này là các địa điểm 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 loại trống 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 đứ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. Lưu ý về việc xử lý: Tham số location_type không giới hạn kết quả tìm kiếm ở các loại vị trí được 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 được chỉ định, sau đó loại bỏ những kết quả không khớp với các loại vị trí được 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 mức địa chỉ đường phố.
    • "RANGE_INTERPOLATED" chỉ trả về những địa chỉ phản ánh giá trị gần đúng (thường là 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 mã địa lý trên mái nhà không có sẵn cho một đị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ư hình nhiều đường (ví dụ: đường phố) hoặc đ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 đâ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, thì 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 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 trình mã hoá địa lý ngược đã trả về nhiều kết quả. Kết quả của "formatted_address" không chỉ là địa chỉ bưu chính mà còn là bất kỳ cách nào để đặt tên cho một vị trí theo đị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ỉ" đối với bộ mã hoá địa lý. Trình mã hoá đị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 mã hoá địa lý ngược khớp với 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 được trả về từ truy vấn trước đó đượ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 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 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 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 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ý ngược.

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

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 tìm ra lý do khiến tính năng 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 rằng 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 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ó chứa tham số result_type hoặc location_type nhưng không chứa 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).
    • result_type hoặc location_type không hợp lệ đã được cung cấp.
  • "UNKNOWN_ERROR" cho biết rằng không thể xử lý yêu cầu do lỗi phía 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 Codes

Trường plus_code trong phản hồi Mã hoá địa lý chứa một Plus Code gần đúng nhất với 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 chứa kết quả Mã hoá địa lý đầy đủ với loại plus_code và địa chỉ chứa mã cộng. Khoảng cách giữa Plus Code được giải mã và điểm yêu cầu được đảm bảo dưới 10 mét.