Các phương thức của Geocoding API v4 có hạn mức mặc định là 25 truy vấn mỗi giây (QPS). Để biết thông tin về cách yêu cầu hạn mức cao hơn, hãy xem bài viết Xem và quản lý hạn mức rồi chọn Geocoding API làm dịch vụ.

Mã hoá địa lý ngược một vị trí

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

Mã hoá địa lý ngược chuyển đổi 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, chẳng hạn như khu dân 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 đối chiếu 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 mã hoá địa lý ngược là một yêu cầu GET HTTP. Bạn có thể chỉ định vị trí dưới dạng một chuỗi không có cấu trúc:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

Hoặc dưới dạng một tập hợp có cấu trúc gồm toạ độ vĩ độ và kinh độ được biểu thị bằng các tham số truy vấn:

https://geocode.googleapis.com/v4/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 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 đề dưới dạng một phần của yêu cầu GET. Ví dụ:

Truyền 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 toạ độ vĩ độ và kinh độ được phân tách bằng dấu phẩy:

https://geocode.googleapis.com/v4/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/v4/geocode/location/37.4225508,-122.0846338"

Truyền 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/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Sử dụng OAuth để đưa ra yêu cầu

Geocoding API phiên bản 4 hỗ trợ OAuth 2.0 để xác thực. Để sử dụng OAuth với Geocoding API, mã thông báo OAuth phải được chỉ định phạm vi chính xác. Geocoding API hỗ trợ các phạm vi sau để sử dụng với mã hoá địa lý ngược:

https://www.googleapis.com/auth/maps-platform.geocode – Sử dụng với tất cả các phương thức Geocoding API.
https://www.googleapis.com/auth/maps-platform.geocode.location – Chỉ sử dụng với GeocodeLocation để 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 phương thức Geocoding API. 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 sản xuất vì đây là phạm vi chung cho phép truy cập vào tất cả các phương thức.

Để biết thêm thông tin và ví dụ, hãy xem bài viết Sử dụng OAuth.

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

Mã hoá địa lý ngược trả về đối tượng GeocodeLocationResponse chứa:

Mảng results gồm các GeocodeResult đối tượng đại diện cho địa điểm.

Bộ mã hoá đị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à 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 ở thành phố Chicago, điểm đã 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 bộ mã hoá địa lý. Bộ 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ường plusCode, thuộc loại PlusCode, chứa Plus code 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ảng results đều chứa một Plus code. Khoảng cách giữa Plus code đã giải mã và điểm yêu cầu là dưới 10 mét.

**Lưu ý:** API không phải lúc nào cũng trả về Plus Codes.

Đố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í mà bạn muốn có địa chỉ gần nhất, dễ đọc.

Thông số tùy chọn

languageCode

Ngôn ngữ mà bạn muốn trả về kết quả.
- Xem danh sách ngôn ngữ được hỗ trợ . Google thường 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ã ngôn ngữ không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT.
- API 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 đó, API 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, đồ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, API sẽ sử dụng kết quả gần đúng 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ề. Bộ mã hoá địa lý diễn giải các từ viết tắt theo cách khác nhau tuỳ thuộc vào ngôn ngữ, chẳng hạn như các từ viết tắt cho loại đường phố hoặc các từ đồng nghĩa có thể hợp lệ ở một ngôn ngữ nhưng không hợp lệ ở ngôn ngữ khác.
regionCode

Mã khu vực dưới dạng giá trị mã CLDR gồm 2 ký tự. Không có giá trị mặc định. Hầu hết các mã CLDR đều giống với mã ISO 3166-1.
Khi mã hoá địa lý một địa chỉ, mã hoá địa lý chuyển tiếp, tham số này có thể ảnh hưởng nhưng không hạn chế hoàn toàn kết quả từ dịch vụ đối với khu vực đã chỉ định. Khi mã hoá địa lý một vị trí hoặc đị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 độ 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 tham số granularity, API sẽ trả về tất cả các địa chỉ khớp với bất kỳ độ chi tiết nào.

Tham số granularity không hạn chế tìm kiếm đối với các độ chi tiết về vị trí đã chỉ định. Thay vào đó, granularity hoạt động như một bộ lọc sau tìm kiếm. API tìm nạp tất cả kết quả cho location đã chỉ định, sau đó loại bỏ những kết quả không khớp với các độ chi tiết về vị trí đã chỉ định.

Nếu bạn chỉ định cả types và granularity, thì API sẽ chỉ trả về những kết quả khớp với cả hai. Ví dụ:
```
https://geocode.googleapis.com/v4/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 các tham số truy vấn riêng biệt. Nếu bạn chỉ định nhiều types tham số, API sẽ trả về tất cả các địa chỉ khớp với bất kỳ loại nào.

Tham số types không hạn chế tìm kiếm đối với(các) loại địa chỉ đã chỉ định. Thay vào đó, types hoạt động như một bộ lọc sau tìm kiếm. API 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ả types và granularity, thì API sẽ chỉ trả về những kết quả khớp với cả hai. Ví dụ:

https://geocode.googleapis.com/v4/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 types trong phần 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 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ẻ với các loại political và locality.

Các loại sau đượ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`	Một giao lộ lớn, thường là của hai con đường lớn.
`political`	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`	Thực thể chính trị quốc gia và thường là loại cấp cao nhất do Bộ mã hoá địa lý trả về.
`administrative_area_level_1`	Một thực thể dân sự 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à các 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 viết tắt `administrative_area_level_1` sẽ khớp chặt chẽ với các phân 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_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à các 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 ba dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính dân sự 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 bốn dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính dân sự 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 năm dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính dân sự 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 sáu dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính dân sự 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 bảy dưới cấp quốc gia. Loại này cho biết một đơn vị hành chính dân sự 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 thực thể chính trị của thành phố hoặc thị trấn đã hợp nhất.
`sublocality`	Một thực thể dân sự cấp một dưới một thành phố. Đố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 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 dân cư có tên.
`premise`	Một vị trí có tên, thường là một toà nhà hoặc tập hợp các 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`	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 code để thay thế đị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 tên). 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 đặc điểm 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, các "POI" này là những thực thể địa phương nổi bật không dễ dàng phù hợp với một danh mục khác, chẳng hạn như "Empire State Building" hoặc "Tháp Eiffel".

Danh sách trống các loại 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).

FieldMask

Tạo mặt nạ trường phản hồi để chỉ định các trường cần trả về trong phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tham số URL $fields hoặc fields, hoặc bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask. Ví dụ: yêu cầu bên dưới sẽ chỉ trả về các trường placeID của phản hồi.
```
curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
```
Phản hồi là:
```
{
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}
```
Xem phần Chọn các trường cần trả về để biết thêm thông tin chi tiết.

Quan trọng: Việc sử dụng mặt nạ trường là một phương pháp thiết kế tốt để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý không cần thiết.

Mã hoá địa lý ngược một vị trí Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

Truyền chuỗi vị trí không có cấu trúc

Truyền vị trí có cấu trúc

Sử dụng OAuth để đưa ra yêu cầu

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

Thông số bắt buộc

vị trí

Thông số tùy chọn

languageCode

regionCode

độ chi tiết

loại

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

FieldMask

Mã hoá địa lý ngược một vị trí