Places UI Kit: Một thư viện có thể sử dụng ngay, cung cấp không gian tuỳ chỉnh và kiểm soát cho nhà phát triển. Hãy dùng thử và chia sẻ ý kiến của bạn về trải nghiệm dùng Bộ giao diện người dùng.

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

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ể dùng mã này để tạo kiểu cho các đa giác ranh giới trong tính năng tạo kiểu dựa trên dữ liệu cho ranh giới. Region Lookup API hỗ trợ 2 loại yêu cầu:

Tra cứu khu vực sẽ 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à quận của Hoa Kỳ) hoặc mã quốc gia ISO-3166-1.
Tìm kiếm theo khu vực sẽ tìm kiếm khu vực 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 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 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ở Region Lookup 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 nội dung 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 nội dung 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, rồi trả về 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à quận 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 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 bạn không chỉ định ngôn ngữ nào, thì ngôn ngữ mặc định là tiếng Anh (Mỹ).

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 bạn không chỉ định giá trị nào, 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

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 không trả về kết quả trù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

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 không trả về kết quả trùng khớp.

Nếu unit_code là "US", 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 được hỗ trợ khác đều không trả về kết quả trù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 sẽ được trả về trong trường hợp có sự mơ hồ. 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ề dưới dạng một đề xuất.

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

Đối tượng LookupRegionResponse chứa một 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, 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ột 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 có chứa một vị trí cụ thể, hãy gọi searchRegion bằng cách chỉ định một SearchRegionRequestData với 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 do khu vực chứa (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 gồm 2 chữ cái theo tiêu chuẩn ISO-3166 cho vị trí cần so khớp. Bạn phải có region_code khi 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 ngôn ngữ nào, thì ngôn ngữ mặc định là tiếng Anh (Mỹ).

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 một 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

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 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", 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à "QUỐC GIA", thì `place` hợp lệ có thể là "Hoa Kỳ", v.v. Bạn phải sử dụng `region_code` khi chỉ định `place`, trừ phi `place_type` là "QUỐC GIA".
`unit_code`	chuỗi	Mã tiểu bang hoặc mã quận theo FIP (chỉ ở Hoa Kỳ) hoặc mã quốc gia theo 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ì 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ã FIP cho California) hoặc "12"(mã FIP 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). `region_code` là thuộc tính bắt buộc khi chỉ định mã FIP. `region_code` sẽ 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 2 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.

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

BẮT BUỘC: Một trong các tham số 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 trong một khu vực cần khớp. Bạn phải có `region_code` khi chỉ định `address`.
`latlng`	LatLng	Vĩ độ và kinh độ nằm trong một khu vực cần 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 2 chữ cái theo tiêu chuẩn ISO-3166 cho vị trí cần so khớp. Bạn phải nhập `region_code` khi 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`	Một 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`	Một 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 hợp nhất.
`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 cặp vĩ độ/kinh độ. Đây là một cặp số thực có độ chính xác kép để biểu thị 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 được 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 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 đề xuất trùng khớp với nội dung đầu vào. Kiểm tra `candidate_place_ids`. nếu có.
`PlaceNameNotUnderstood`	Tên địa điểm bạn 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ị 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.