Thông báo: Kiểu bản đồ cơ sở mới sắp ra mắt trên Nền tảng Google Maps. Bản cập nhật này về kiểu bản đồ bao gồm bảng màu mặc định mới, ghim hiện đại và các điểm cải tiến về trải nghiệm và khả năng sử dụng bản đồ. Tất cả kiểu bản đồ sẽ được tự động cập nhật 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 sử dụng 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

Với API Tìm kiếm 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ể sử 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:

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

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

Các loại địa điểm theo khu vực 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 Tìm kiếm theo khu vực, hãy làm theo các bước sau:

Bật API Tìm kiếm theo 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ở Tìm kiếm theo khu vực cung cấp một tập hợp các hàm và kiểu TypeScript mà bạn phải nhập vào mã của mình.

Đối với các 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 các yêu cầu tìm kiếm theo khu vực, hãy nhập những thông tin 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ẽ lấy 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 một 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 của Hoa Kỳ) hoặc mã quốc gia theo 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 ISO-3166 gồm hai chữ cái để so khớp vị trí. 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 bạn không chỉ định, giá trị mặc định sẽ là en-US.

Ví dụ sau đây cho thấy một yêu cầu tra cứu cho Newark, New Jersey.

// 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 bắt buộc phải sử dụng tham số place hoặc unit_code. Nếu không chỉ định giá trị nào, hệ thống sẽ trả về lỗi.

Bạn phải sử dụng 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ã đị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 của California. Tất cả các loại khác được hỗ trợ sẽ trả về kết quả không khớp.

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

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

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

Nếu unit_code là "US" (Hoa Kỳ), API sẽ trả về các kết quả sau khi bạn chỉ định các place_type sau:

place_type: COUNTRY

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

Nếu không tìm thấy kết quả trùng khớp, matched_place_id sẽ không được đặt.

Mã địa điểm đề xuất đượ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 của Hạt Santa Clara sẽ được trả về dưới dạng đề xuất.

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 kết quả. Nếu không tìm thấy kết quả nào, các mã địa điểm có độ tin cậy thấp hơn sẽ được trả về dưới dạng mã đề xuất, cùng với mã lỗi chứa thông tin gỡ lỗi.

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

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

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

address hoặc latlng hoặc place_id (bắt buộc) Chứa một chuỗi địa chỉ không có cấu trúc, latlng hoặc mã địa điểm có trong vùng (ví dụ: địa điểm yêu thích, toà nhà, v.v.). Nếu bạn không chỉ định thì 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.
region_code Mã quốc gia/khu vực ISO-3166 gồm hai chữ cái để so khớp vị trí. region_code là bắt buộc khi bạn chỉ định address.
language Mã ngôn ngữ BCP-47, chẳng hạn như "en-US" hoặc "sr-Latn". Nếu bạn không chỉ định, giá trị mặc định sẽ là en-US.

Ví dụ sau đây cho thấy một yêu cầu tra cứu cho Burbank, California.

// 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 tìm kiếm theo khu vực

Đối tượng SearchRegionResponse chứa matched_place_id nếu tìm thấy kết quả. Trong trường hợp không khớp, phản hồi sẽ chứa một hoặc nhiều mã địa điểm đề xuất và 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	Mô tả
`place`	chuỗi	Tên của khu vực cần so khớp với 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à "locality" (khu vực), thì `place` hợp lệ có thể là "Palo Alto, CA". Nếu `place_type` là "POSTAL_CODE", thì place_name hợp lệ có thể là "94109". Nếu `place_type` là "COUNTRY", thì `place` hợp lệ có thể là "United States" (Hoa Kỳ), v.v. `region_code` là bắt buộc khi chỉ định `place`, trừ phi `place_type` là "COUNTRY".
`unit_code`	chuỗi	Mã tiểu bang hoặc mã hạt của FIP (chỉ ở Hoa Kỳ) hoặc mã quốc gia theo ISO-3166-1 cần 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ì unit_code hợp lệ có thể là "US" (mã ISO-3166-1 Alpha-2 cho Hoa Kỳ) hoặc "BR" (mã ISO-3166-1 Alpha-2 cho Brazil). Nếu `place_type` là `ADMINISTRATIVE_AREA_LEVEL_1` (tiểu bang) và region_code là "US", thì unit_code hợp lệ có thể là "6" (mã FIPs cho California) hoặc "12"(mã FIPs cho Florida). Nếu place_type là `ADMINISTRATIVE_AREA_LEVEL_2` (quận) và region_code là "US", thì unit_code hợp lệ có thể là "6001" (mã FIPs cho Quận Alameda ở California) hoặc "12086" (mã FIPs cho Quận Miami-Dade ở Florida). Bắt buộc 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`	chuỗi	Mã quốc gia/khu vực ISO-3166 gồm hai chữ cái cho vị trí mà bạn đang cố gắng khớp. Bạn không bắt buộc phải sử dụng region_code nếu `place_type` là "COUNTRY".
`language_code`	chuỗi	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ó ngôn ngữ nào được yêu cầu, thì ngôn ngữ mặc định sẽ là tiếng Anh.

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

BẮT BUỘC: Một trong các giá trị address, latlng hoặc place_id.

Trường	Loại	Mô tả
`address`	chuỗi	Một địa chỉ đường phố không có cấu trúc nằm bên trong một khu vực cần khớp. `region_code` là bắt buộc khi bạn chỉ định `address`.
`latlng`	LatLng	Vĩ độ và kinh độ nằm trong một khu vực cần so khớp.
`place_id`	chuỗi	Mã địa điểm nằm trong một khu vực cần 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`	chuỗi	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 và địa chỉ của địa điểm được yêu cầu. Nếu không có yêu cầu nào, thì ngôn ngữ mặc định sẽ là tiếng Anh.
`region_code`	chuỗi	Mã quốc gia/khu vực ISO-3166 gồm hai chữ cái để so khớp vị trí. `region_code` là bắt buộc khi bạn chỉ định địa chỉ.

Loại địa điểm

Giá trị	Mô tả
`POSTAL_CODE`	Mã bưu chính dùng để gửi thư trong nước.
`ADMINISTRATIVE_AREA_LEVEL_1`	Một pháp nhân dân sự cấp 1 ở cấp thấp hơn 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`	Một pháp nhân dân sự cấp hai bên dưới cấp quốc gia. Tại Hoa Kỳ, các cấp hành chính này là hạt.
`LOCALITY`	Một thực thể chính trị là thành phố hoặc thị trấn được hợp nhất.
`COUNTRY`	Thực thể chính trị quốc gia, thường là loại thứ tự cao nhất.

LatLng

Một đối tượng đại diện cho một cặp vĩ độ/kinh độ. Giá trị này được biểu thị dưới dạng một cặp số thực để thể hiện vĩ độ và kinh độ theo độ. 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	Mô tả
`latitude`	gấp đôi	Vĩ độ tính bằng độ. 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 bằng độ. 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ị	Mô tả
`UnknownError`	Đã xảy ra lỗi không xác định.
`NoMatchFound`	Yêu cầu không có kết quả trùng khớp, hãy kiểm tra `candidate_place_ids` nếu có.
`AddressNotUnderstood`	Không mã hoá địa lý được cho địa chỉ bạn cung cấp.
`PlaceTypeMismatch`	Loại địa điểm trong phản hồi không khớp với loại địa điểm của yêu cầu. Ví dụ: `locality` được yêu cầu nhưng `administrative_area_level_2` lại được trả về.
`MultipleCandidatesFound`	Nhiều đề xuất đã được so khớp với dữ liệu đầu vào. Kiểm tra `candidate_place_ids`. nếu có.
`PlaceNameNotUnderstood`	Không phân giải được tên địa điểm thành 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 ở định dạng chính xác.
`PlaceTypeNotAllowed`	Mã địa điểm được so khớp không có trong danh sách cho phép của loại địa điểm và quốc gia.