Nhận Maps Demo Key: Dùng thử miễn phí một số tính năng của Maps JavaScript API và Places UI Kit bằng Maps Demo Key mà không cần cung cấp thông tin thanh toán.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

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

Với Region Lookup API, bạn có thể tìm 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 trong tính năng định kiểu dựa trên dữ liệu cho ranh giới. Region Lookup API hỗ trợ hai loại yêu cầu:

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

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

Hỗ trợ các loại địa điểm theo khu vực sau: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Cài đặt thư viện

Để sử dụng Region Lookup API, hãy làm theo các bước sau:

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

Nhập các 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 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 nội dung 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 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ã đị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 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 hai 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ó ngôn ngữ nào được chỉ định, thì ngôn ngữ mặc định là en-US.

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

Tham số region_code là bắt buộc, 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

matched_place_id kết quả: Mã địa điểm cho California. Tất cả các loại được hỗ trợ khác đều 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à "US", thì API sẽ trả về mã địa điểm cho California:

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

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

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

place_type: COUNTRY

matched_place_id kết quả: mã địa điểm cho Hoa Kỳ. Tất cả các loại được hỗ trợ khác đều 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 một đề 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ả, thì mã địa điểm có độ tin cậy thấp hơn sẽ được trả về dưới dạng mã nhận dạng đề 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 một 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 khu vực (ví dụ: địa điểm yêu thích, 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.
region_code 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 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 không có ngôn ngữ nào được chỉ định, thì ngôn ngữ mặc định là en-US.

Ví dụ sau đây cho thấy một yêu cầu tra cứu cho 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 tìm kiếm 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ột mã lỗi.

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

Tài liệu tham khảo

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

Trường	Loại	Mô tả
`place`	chuỗi	Tên của khu vực cần so khớp với Mã đị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", 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à "Hoa Kỳ", v.v. `region_code` là bắt buộc khi bạn chỉ định `place`, trừ phi `place_type` là "COUNTRY".
`unit_code`	chuỗi	Mã tiểu bang hoặc quận theo 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ã FIP cho Quận Alameda ở California) hoặc "12086" (mã FIP cho Quận Miami-Dade ở Florida). Bạn phải cung cấp `region_code` khi chỉ định mã FIP. `region_code` bị bỏ qua đối với mã quốc gia theo 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 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. region_code là không bắt buộc 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 và địa chỉ của địa điểm đượ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.

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

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	Địa chỉ đường phố không có cấu trúc nằm trong một khu vực để so 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ó ngôn ngữ nào được yêu cầu, thì ngôn ngữ mặc định sẽ là tiếng Anh.
`region_code`	chuỗi	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 bạn chỉ định địa chỉ.

Loại địa điểm

Giá trị	Mô tả
`POSTAL_CODE`	Mã bưu chính, được dùng để gửi thư bưu chính trong quốc gia.
`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.
`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.
`LOCALITY`	Một pháp nhân chính trị của thành phố hoặc thị trấn đã đăng ký thành lập.
`COUNTRY`	Thực thể chính trị quốc gia, thường là loại cấp 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 có độ chính xác gấp đôi để thể hiện vĩ độ và kinh độ. Trừ phi được chỉ đị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 khoảng `[-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 khoảng từ `[-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 khớp, hãy kiểm tra `candidate_place_ids` nếu có.
`AddressNotUnderstood`	Không mã hoá địa lý được cho địa chỉ đã 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 trong yêu cầu. Ví dụ: `locality` được yêu cầu nhưng `administrative_area_level_2` được trả về.
`MultipleCandidatesFound`	Nhiều ứng viên phù hợp với thông tin đầu vào. Kiểm tra `candidate_place_ids`. nếu có.
`PlaceNameNotUnderstood`	Tên địa điểm được cung cấp không phân giải được 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 trùng khớp không nằm trong danh sách cho phép về loại địa điểm và quốc gia.