Kiểu bản đồ mới sắp xuất hiện trên Nền tảng Google Maps. Bản cập nhật này để tạo kiểu bản đồ bao gồm một bảng màu mặc định mới và các cải tiến về trải nghiệm bản đồ cũng như khả năng hữu dụng. Tất cả kiểu bản đồ sẽ được cập nhật tự động vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn tham gia sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

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

Sử dụng API Tra cứu khu vực

Thông qua API Tra cứu khu vực, bạn có thể tìm thấy mã địa điểm cho các khu vực. Bạn có thể dùng mã này để tạo kiểu cho đa giác ranh giới theo kiểu dựa trên dữ liệu cho ranh giới. API Tra cứu khu vực hỗ trợ hai loại yêu cầu:

Tra cứu khu vực tra cứu một khu vực theo tên địa điểm, mã FIPS (chỉ dành cho các tiểu bang và hạt của Hoa Kỳ) hoặc mã quốc gia theo ISO-3166-1.
Tìm kiếm khu vực tìm kiếm khu vực có chứa một vị trí cụ thể như được chỉ định theo địa chỉ, LatLng hoặc mã địa điểm.

Các loại địa điểm cho khu vực được hỗ trợ

Các loại địa điểm sau đây được hỗ trợ: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Cài đặt thư viện

Để sử dụng API Tra cứu khu vực, hãy làm theo các bước sau:

Bật API Tra cứu khu vực trong bảng điều khiển.
Cài đặt thư viện nguồn mở: npm install @googlemaps/region-lookup

Nhập phần phụ thuộc từ thư viện

Thư viện nguồn mở Tra cứu khu vực cung cấp một tập hợp các hàm và kiểu nhập TypeScript mà bạn phải nhập vào mã của mình.

Đối với yêu cầu tra cứu khu vực, hãy nhập những thông tin sau:

import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

Đối với yêu cầu tìm kiếm theo khu vực, hãy nhập những mục sau:

import {
  searchRegion,
  RegionSearchValue,
  SearchRegionRequestData,
  SearchRegionResponse
} from "@googlemaps/region-lookup";

Yêu cầu tra cứu khu vực

Yêu cầu tra cứu khu vực sẽ nhận một tên địa điểm hoặc mã nhận dạng và trả về một mã địa điểm. Để tra cứu một khu vực, hãy gọi lookupRegion(), chỉ định LookupRegionRequestData bằng các tham số sau:

place hoặc unit_code (bắt buộc) Tên khu vực (place) hoặc unit_code của địa điểm. unit_code có thể là mã FIPS (chỉ dành cho các tiểu bang và hạt ở Hoa Kỳ) hoặc mã quốc gia theo tiêu chuẩn ISO-3166-1.
place_type (bắt buộc) Giá trị loại địa điểm cho loại địa điểm cần tra cứu.
region_code Mã quốc gia/khu vực gồm 2 chữ cái theo tiêu chuẩn ISO-3166 cho vị trí cần so khớp. region_code là không bắt buộc nếu place_type là COUNTRY.
language Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn". Nếu không có giá trị nào được chỉ định, giá trị mặc định sẽ là en-US.

Ví dụ sau đây minh hoạ một yêu cầu tra cứu cho Newark, NJ.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

Bạn phải sử dụng tham số place hoặc unit_code. Nếu không có giá trị nào được chỉ định, hệ thống sẽ trả về lỗi.

Bạn phải tham số region_code, trừ phi place_type là COUNTRY.

place và unit_code chỉ định một vị trí để so khớp với một mã địa điểm. Ví dụ: nếu place là "California" và place_type là ADMINISTRATIVE_AREA_LEVEL_1, thì API sẽ trả về mã địa điểm cho California dưới dạng matched_place_id:

place_type: ADMINISTRATIVE_AREA_LEVEL_1

Kết quả matched_place_id: mã địa điểm cho California. Tất cả các loại được hỗ trợ khác đều trả về kết quả không khớp.

Nếu unit_code là "6" (Mã FIPS cho California), place_type là ADMINISTRATIVE_AREA_LEVEL_1 và region_code là "Hoa Kỳ", thì API sẽ trả về mã địa điểm cho California:

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

Kết quả matched_place_id: mã địa điểm cho California. Tất cả các loại được hỗ trợ khác đều trả về kết quả không khớp.

Nếu unit_code là "US", thì API sẽ trả về các kết quả sau khi các place_type sau được chỉ định:

place_type: COUNTRY

Kết quả matched_place_id: mã địa điểm của Hoa Kỳ. Tất cả các loại được hỗ trợ khác đều trả về kết quả không khớp.

Nếu không tìm thấy kết quả trùng khớp thì matched_place_id chưa được thiết lập.

Mã địa điểm ứng cử viên được trả về trong trường hợp không rõ ràng. Ví dụ: nếu place là "Hạt Santa Clara" và place_type là LOCALITY, thì mã địa điểm cho Hạt Santa Clara sẽ được trả về với tư cách ứng cử viên.

Phản hồi tra cứu khu vực

Đối tượng LookupRegionResponse chứa matched_place_id nếu tìm thấy một kết quả. Nếu không tìm thấy kết quả nào, thì các mã địa điểm có độ tin cậy thấp hơn sẽ được trả về dưới dạng mã ứng viên, cùng với một mã lỗi chứa thông tin gỡ lỗi.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Yêu cầu tìm kiếm khu vực

Để tìm khu vực có chứa một vị trí cụ thể, hãy gọi searchRegion chỉ định SearchRegionRequestData với các tham số sau:

address hoặc latlng hoặc place_id (bắt buộc) Chứa chuỗi địa chỉ không có cấu trúc, latlng hoặc mã địa điểm có trong khu vực (ví dụ: POI, toà nhà, v.v.). Nếu không có giá trị nào được chỉ định, hệ thống sẽ trả về lỗi.
place_type (bắt buộc) Giá trị loại địa điểm cho loại khu vực cần tìm kiếm.
region_code Mã quốc gia/khu vực gồm 2 chữ cái theo tiêu chuẩn ISO-3166 cho vị trí cần so khớp. region_code là bắt buộc khi address đã được chỉ định.
language Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn". Nếu không có giá trị nào được chỉ định, giá trị mặc định sẽ là en-US.

Ví dụ sau đây thể hiện một yêu cầu tra cứu đối với Burbank, CA.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

Phản hồi khi tìm kiếm theo khu vực

Đối tượng SearchRegionResponse chứa matched_place_id nếu tìm thấy một kết quả. Trong trường hợp không so khớp được, phản hồi sẽ chứa một hoặc nhiều mã địa điểm đề xuất và một mã lỗi.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

Tài liệu tham khảo

Giá trị nhận dạng `LookupRegionRequestData`

Trường	Loại	Nội dung mô tả
`place`	string	Tên của khu vực để so khớp với một mã địa điểm. Sử dụng trường `place` kết hợp với `place_type` để tra cứu mã địa điểm của khu vực. Ví dụ: nếu `place_type` là "địa phương", thì `place` hợp lệ có thể là "Palo Alto, CA". Nếu `place_type` là "POSTAL_CODE", thì tên_địa_điểm hợp lệ có thể là "94109". Nếu `place_type` là "COUNTRY", thì `place` hợp lệ có thể là "Hoa Kỳ", v.v. Bạn phải chỉ định `region_code` khi `place` được chỉ định trừ phi `place_type` là "COUNTRY".
`unit_code`	string	Mã tiểu bang hoặc mã hạt của FIP (chỉ ở Hoa Kỳ) hoặc mã quốc gia theo tiêu chuẩn ISO-3166-1 cần được so khớp. Trường `unit_code` được dùng kết hợp với `place_type` để tra cứu mã địa điểm của khu vực. Ví dụ: Nếu `place_type` là `COUNTRY`, thì mã đơn vị hợp lệ có thể là "US" (mã ISO-3166-1 Alpha-2 đối với Hoa Kỳ) hoặc "BR" (mã ISO-3166-1 Alpha-2 đối với Brazil). Nếu `place_type` là `ADMINISTRATIVE_AREA_LEVEL_1` (tiểu bang) và mã khu vực là "US", thì mã đơn_vị hợp lệ có thể là "6" (mã FIP cho California) hoặc "12"(mã FIP cho Florida). Nếu place_type là `ADMINISTRATIVE_AREA_LEVEL_2` (hạt) và mã khu vực là "US", thì mã đơn vị hợp lệ có thể là "6001" (mã FIP cho Hạt Alameda ở California) hoặc "12086" (mã FIP cho Hạt Miami-Dade ở Florida). Bạn phải có `region_code` khi chỉ định mã FIPs. `region_code` sẽ bị bỏ qua đối với mã quốc gia theo tiêu chuẩn ISO-3166-1.
`place_type`	PlaceType	Bắt buộc. Loại khu vực cần so khớp.
`region_code`	string	Mã quốc gia/khu vực gồm hai chữ cái theo tiêu chuẩn ISO-3166 cho vị trí mà bạn đang cố gắng so khớp. Mã vùng là thuộc tính không bắt buộc nếu `place_type` là "COUNTRY".
`language_code`	string	Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn", tương ứng với ngôn ngữ mà tên địa điểm và địa chỉ được yêu cầu. Nếu không có yêu cầu nào, thì giá trị mặc định sẽ là tiếng Anh.

Giá trị nhận dạng `SearchRegionRequestData`

BẮT BUỘC: Một trong số address, latlng hoặc place_id.

Trường	Loại	Nội dung mô tả
`address`	string	Địa chỉ đường phố không có cấu trúc nằm trong một khu vực để so khớp. Bạn phải chỉ định `region_code` khi `address` đã được chỉ định.
`latlng`	LatLng	Vĩ độ và kinh độ nằm trong một khu vực để khớp.
`place_id`	string	Mã địa điểm nằm trong một khu vực để so khớp.
`place_type`	loại địa điểm	Bắt buộc. Loại khu vực cần so khớp.
`language_code`	string	Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn", tương ứng với ngôn ngữ mà tên địa điểm và địa chỉ được yêu cầu. Nếu không có yêu cầu nào, thì giá trị mặc định sẽ là tiếng Anh.
`region_code`	string	Mã quốc gia/khu vực gồm hai chữ cái theo tiêu chuẩn ISO-3166 cho vị trí cần so khớp. `region_code` là bắt buộc khi địa chỉ được chỉ định.

Loại địa điểm

Giá trị	Nội dung mô tả
`POSTAL_CODE`	Mã bưu chính, dùng để gửi thư qua đường bưu điện trong quốc gia.
`ADMINISTRATIVE_AREA_LEVEL_1`	Pháp nhân dân sự bậc nhấ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.
`ADMINISTRATIVE_AREA_LEVEL_2`	Pháp nhân 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.
`LOCALITY`	Một pháp nhân chính trị thành phố hoặc thị trấn được thành lập.
`COUNTRY`	Pháp nhân chính trị quốc gia, thường là loại đơn đặt hàng cao nhất.

LatLng

Một đối tượng đại diện cho cặp vĩ độ/kinh độ. Thuộc tính này được biểu thị dưới dạng một cặp đối tượng kép để đại diện cho độ vĩ độ và độ kinh độ. Trừ phi có quy định khác, đối tượng này phải tuân thủ tiêu chuẩn WGS84. Giá trị phải nằm trong phạm vi đã chuẩn hoá.

Trường	Loại	Nội dung mô tả
`latitude`	gấp đôi	Vĩ độ tính theo độ. Giá trị này phải nằm trong phạm vi `[-90.0, +90.0]`. Ví dụ: `47.47583476464538`.
`longitude`	gấp đôi	Kinh độ tính theo độ. Giá trị này phải nằm trong phạm vi `[-180.0, +180.0]`. Ví dụ: `-121.73858779269906`.

Mã lỗi

Giá trị	Nội dung mô tả
`UnknownError`	Đã xảy ra lỗi không xác định.
`NoMatchFound`	Yêu cầu không cho kết quả nào phù hợp, hãy kiểm tra `candidate_place_ids` nếu có.
`AddressNotUnderstood`	Không mã hoá được địa lý cho địa chỉ đã cung cấp.
`PlaceTypeMismatch`	Loại địa điểm trong câu trả lời không khớp với loại địa điểm trong yêu cầu. Ví dụ: `locality` được yêu cầu nhưng trả về `administrative_area_level_2`.
`MultipleCandidatesFound`	Nhiều đề xuất khớp với câu trả lời đã nhập. Xem `candidate_place_ids`. nếu có.
`PlaceNameNotUnderstood`	Tên địa điểm đã cung cấp không phân giải được cho một khu vực.
`UnitCodeNotFound`	Không tìm thấy mã đơn vị. Xác minh rằng mã đơn vị là hợp lệ và được cung cấp ở đúng định dạng.
`PlaceTypeNotAllowed`	Mã địa điểm trùng khớp không có trong danh sách cho phép của loại địa điểm và quốc gia.