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ặcunit_code
(bắt buộc) Tên khu vực (place
) hoặcunit_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ặclatlng
hoặcplace_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 khiaddress
đã đượ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. |