ใช้ Region Lookup API

ผลิตภัณฑ์หรือฟีเจอร์นี้อยู่ในขั้นทดลอง (ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไป) ผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจมีการรองรับที่จำกัด และการเปลี่ยนแปลงของผลิตภัณฑ์และฟีเจอร์ก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปอาจใช้ไม่ได้กับเวอร์ชันก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไป ข้อเสนอก่อนเวอร์ชันสำหรับผู้ใช้ทั่วไปจะอยู่ภายใต้ข้อกำหนดเฉพาะของบริการ Google Maps Platform ดูข้อมูลเพิ่มเติมได้ที่คำอธิบายขั้นตอนการเปิดตัว

เมื่อใช้ Region Lookup API คุณจะสามารถดูรหัสสถานที่สําหรับภูมิภาคต่างๆ ซึ่งใช้จัดรูปแบบรูปหลายเหลี่ยมของขอบเขตในการจัดรูปแบบตามข้อมูลสำหรับขอบเขตได้ API การค้นหาภูมิภาคสนับสนุนคำขอสองประเภท ได้แก่

• การค้นหาภูมิภาคจะค้นหาภูมิภาคตามชื่อสถานที่ รหัส FIPS (รัฐและเคาน์ตีในสหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ ISO-3166-1
• การค้นหาภูมิภาคจะค้นหาภูมิภาคซึ่งมีสถานที่ที่เจาะจงตามที่ระบุโดยที่อยู่ LatLng หรือรหัสสถานที่

ประเภทสถานที่ในภูมิภาคที่รองรับ

ประเภทสถานที่ในภูมิภาคต่อไปนี้ได้รับการสนับสนุน: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality

ติดตั้งไลบรารี

หากต้องการใช้ API การค้นหาภูมิภาค ให้ทำตามขั้นตอนต่อไปนี้

1. เปิดใช้ API การค้นหาภูมิภาคในคอนโซล
2. ติดตั้งไลบรารีโอเพนซอร์ส: npm install @googlemaps/region-lookup

นำเข้าทรัพยากร Dependency จากไลบรารี

ไลบรารีโอเพนซอร์สของการค้นหาภูมิภาคมีชุดฟังก์ชันและการพิมพ์ TypeScript ที่คุณต้องนำเข้าไปยังโค้ด

• สำหรับคำขอการค้นหาภูมิภาค ให้นำเข้าข้อมูลต่อไปนี้

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

• สำหรับคำขอการค้นหาภูมิภาค ให้นำเข้าข้อมูลต่อไปนี้

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

ข้อควรระวัง: Region Lookup API และไลบรารีโอเพนซอร์สสำหรับ JavaScript คือรุ่นทดลอง

คำขอค้นหาภูมิภาค

คำขอค้นหาภูมิภาคจะใช้ชื่อสถานที่หรือรหัสตัวระบุ และแสดงผลรหัสสถานที่ หากต้องการค้นหาภูมิภาค ให้เรียกใช้ lookupRegion() โดยระบุ LookupRegionRequestData ด้วยพารามิเตอร์ต่อไปนี้

• place หรือ unit_code (ต้องระบุ) ชื่อภูมิภาค (place) หรือ unit_code ของสถานที่ unit_code เป็นได้ทั้งรหัส FIPS (รัฐและเคาน์ตีในสหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ ISO-3166-1
• place_type (ต้องระบุ) ค่าประเภทสถานที่สำหรับประเภทสถานที่ที่จะค้นหา
• region_code รหัสประเทศ/ภูมิภาค 2 ตัวอักษรตามมาตรฐาน ISO-3166 สำหรับสถานที่ตั้งที่ตรงกัน คุณจะระบุ region_code หรือไม่ก็ได้หาก Place_type เป็น COUNTRY
• language รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" หากไม่ได้ระบุไว้ ค่าเริ่มต้นจะเป็น en-US

ตัวอย่างต่อไปนี้แสดงคำขอค้นหาเมืองนวร์ก รัฐนิวเจอร์ซีย์

// 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 });

ต้องมีพารามิเตอร์ place หรือ unit_code หากไม่ได้ระบุ ระบบจะแสดงข้อผิดพลาด

ต้องระบุพารามิเตอร์ region_code ยกเว้นกรณีที่ place_type คือ COUNTRY

place และ unit_code ระบุตำแหน่งที่จะจับคู่รหัสสถานที่ เช่น หาก place คือ "แคลิฟอร์เนีย" และ place_type คือ ADMINISTRATIVE_AREA_LEVEL_1 API จะแสดงรหัสสถานที่สำหรับแคลิฟอร์เนียเป็น matched_place_id

• place_type: ADMINISTRATIVE_AREA_LEVEL_1

  ผลลัพธ์ matched_place_id รายการ: รหัสสถานที่สำหรับเชียงใหม่ ส่วนประเภทอื่นๆ ที่รองรับจะแสดงผลลัพธ์ที่ไม่ตรงกัน

หาก unit_code คือ "6" (รหัส FIPS สำหรับแคลิฟอร์เนีย) place_type จะเป็น ADMINISTRATIVE_AREA_LEVEL_1 และ region_code คือ "US" API จะแสดงรหัสสถานที่สำหรับแคลิฟอร์เนีย

• place_type: ADMINISTRATIVE_AREA_LEVEL_1

• region_code: US

  ผลลัพธ์ matched_place_id รายการ: รหัสสถานที่สำหรับเชียงใหม่ ส่วนประเภทอื่นๆ ที่รองรับจะแสดงผลลัพธ์ที่ไม่ตรงกัน

หาก unit_code เป็น "US" API จะแสดงผลลัพธ์ต่อไปนี้เมื่อระบุ place_type ต่อไปนี้

• place_type: COUNTRY

  ผลลัพธ์ matched_place_id รายการ: รหัสสถานที่สำหรับสหรัฐอเมริกา ส่วนประเภทอื่นๆ ที่รองรับจะแสดงผลลัพธ์ที่ไม่ตรงกัน

หากไม่พบรายการที่ตรงกัน แสดงว่าไม่มีการตั้งค่า matched_place_id

หากข้อมูลไม่ชัดเจน รหัสสถานที่ของผู้สมัครจะถูกส่งกลับคืนมา เช่น หาก place คือ "เทศมณฑลซานตาคลารา" และ place_type คือ LOCALITY รหัสสถานที่ของเทศมณฑลซานตาคลาราจะถูกส่งคืนในฐานะผู้สมัคร

การตอบกลับการค้นหาภูมิภาค

ออบเจ็กต์ LookupRegionResponse มี matched_place_id หากพบผลลัพธ์ หากไม่พบผลลัพธ์ ระบบจะส่งรหัสสถานที่ที่มีความเชื่อมั่นต่ำกว่าเป็นรหัสผู้สมัคร พร้อมด้วยรหัสข้อผิดพลาดที่มีข้อมูลการแก้ไขข้อบกพร่อง

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

คำขอการค้นหาภูมิภาค

หากต้องการค้นหาภูมิภาคที่มีสถานที่ตั้งเฉพาะ ให้เรียก searchRegion โดยระบุ SearchRegionRequestData ด้วยพารามิเตอร์ต่อไปนี้

• address หรือ latlng หรือ place_id (ต้องระบุ) มีสตริงที่อยู่ที่ไม่มีโครงสร้าง latlng หรือรหัสสถานที่ที่มีอยู่ตามภูมิภาค (เช่น จุดที่น่าสนใจ อาคาร เป็นต้น) หากไม่ระบุ ระบบจะแสดงผล ข้อผิดพลาด
• place_type (ต้องระบุ) ค่าประเภทสถานที่สำหรับประเภทภูมิภาคที่ต้องการค้นหา
• region_code รหัสประเทศ/ภูมิภาค 2 ตัวอักษรตามมาตรฐาน ISO-3166 สำหรับสถานที่ตั้งที่ตรงกัน ต้องระบุ region_code เมื่อระบุ address
• language รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" หากไม่ได้ระบุไว้ ค่าเริ่มต้นจะเป็น en-US

ตัวอย่างต่อไปนี้แสดงคำขอการค้นหาสำหรับเบอร์แบงก์ แคนาดา

// 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 });

การตอบกลับการค้นหาภูมิภาค

ออบเจ็กต์ SearchRegionResponse มี matched_place_id หากพบผลลัพธ์ ในกรณีที่การจับคู่ไม่สำเร็จ การตอบกลับจะมีรหัสสถานที่และรหัสข้อผิดพลาดที่รอพิจารณาอย่างน้อย 1 รายการ

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

ข้อมูลอ้างอิง

ตัวระบุ LookupRegionRequestData รายการ

ฟิลด์	ประเภท	คำอธิบาย
place	string	ชื่อของภูมิภาคที่จะจับคู่กับรหัสสถานที่ ใช้ช่อง place ร่วมกับ place_type เพื่อค้นหารหัสสถานที่ของภูมิภาค เช่น หาก place_type คือ "ย่าน" place ที่ถูกต้องจะเป็น "Palo Alto, CA" ได้ หาก place_type เป็น "POSTAL_CODE" ชื่อ Place_name ที่ถูกต้องจะเป็น "94109" ได้ หาก place_type เป็น "COUNTRY" place ที่ถูกต้องอาจเป็น "สหรัฐอเมริกา" ฯลฯ ต้องมี region_code เมื่อระบุ place เว้นแต่ว่า place_type จะเป็น "COUNTRY"
unit_code	string	รหัสรัฐหรือรหัสเคาน์ตี (สหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ ISO-3166-1 ที่จะจับคู่ ช่อง unit_code ใช้ร่วมกับ place_type เพื่อค้นหารหัสสถานที่ของภูมิภาค เช่น หาก place_type คือ COUNTRY รหัส unit_code ที่ถูกต้องอาจเป็น "US" (รหัส ISO-3166-1 Alpha-2 สำหรับสหรัฐอเมริกา) หรือ "BR" (รหัส ISO-3166-1 Alpha-2 สำหรับบราซิล) หาก place_type คือ ADMINISTRATIVE_AREA_LEVEL_1 (รัฐ) และregion_code คือ "US" unit_code ที่ถูกต้องอาจเป็น "6" (รหัส FIP สำหรับแคลิฟอร์เนีย) หรือ "12"(รหัส FTP ของ ฟลอริดา) หาก Place_type คือ ADMINISTRATIVE_AREA_LEVEL_2 (เคาน์ตี) และรหัสภูมิภาค [region_code] เป็น "US" หน่วย [unit_code] ที่ถูกต้องอาจเป็น "6001" (รหัส FIP ของอลาเมดาเคาน์ตีในแคลิฟอร์เนีย) หรือ "12086" (รหัส FIP ของไมอามี-เดดเคาน์ตีในฟลอริดา) ต้องระบุ region_code เมื่อระบุรหัส FIP ระบบจะละเว้น region_code สำหรับรหัสประเทศ ISO-3166-1
place_type	PlaceType	ต้องระบุ ประเภทของภูมิภาคที่จะจับคู่
region_code	string	รหัสประเทศ/ภูมิภาค 2 ตัวอักษรตามมาตรฐาน ISO-3166 ของสถานที่ตั้งที่คุณพยายามจับคู่ คุณจะป้อนรหัสภูมิภาค (region_code) หรือไม่ก็ได้หาก place_type คือ "COUNTRY"
language_code	string	รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" ที่สอดคล้องกับภาษาที่มีการขอชื่อและที่อยู่ของสถานที่ หากไม่มีคำขอ ค่าเริ่มต้นจะเป็นภาษาอังกฤษ

ตัวระบุ SearchRegionRequestData รายการ

ต้องระบุ: 1 จาก address, latlng หรือ place_id

ฟิลด์	ประเภท	คำอธิบาย
address	string	ที่อยู่ที่ไม่มีโครงสร้างซึ่งอยู่ภายในภูมิภาคที่จะจับคู่ได้ ต้องระบุ region_code เมื่อระบุ address
latlng	LatLng	ละติจูดและลองจิจูดที่อยู่ภายในภูมิภาคที่จะจับคู่
place_id	string	รหัสสถานที่ที่อยู่ในภูมิภาคที่จะจับคู่
place_type	ประเภทสถานที่	ต้องระบุ ประเภทของภูมิภาคที่จะจับคู่
language_code	string	รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" ซึ่งสอดคล้องกับภาษาที่ใช้ขอชื่อและที่อยู่ของสถานที่ หากไม่มีคำขอ ค่าเริ่มต้นจะเป็นภาษาอังกฤษ
region_code	string	รหัสประเทศ/ภูมิภาค 2 ตัวอักษรตามมาตรฐาน ISO-3166 สำหรับการจับคู่สถานที่ตั้ง ต้องระบุ region_code เมื่อระบุที่อยู่

ประเภทสถานที่

ค่า	คำอธิบาย
POSTAL_CODE	รหัสไปรษณีย์ที่ใช้ระบุที่อยู่ทางไปรษณีย์ภายในประเทศ
ADMINISTRATIVE_AREA_LEVEL_1	นิติบุคคลพลเรือนอันดับ 1 ที่ต่ำกว่าระดับประเทศ ในสหรัฐอเมริกา ระดับบริหารเหล่านี้เป็นรัฐ
ADMINISTRATIVE_AREA_LEVEL_2	การปกครองลำดับที่ 2 ที่ต่ำกว่าระดับประเทศ ในสหรัฐอเมริกา ระดับบริหารเหล่านี้เป็นเขต
LOCALITY	หน่วยงานทางการเมืองของเมืองหรือเมืองที่ก่อตั้งขึ้น
COUNTRY	หน่วยงานทางการเมืองแห่งชาติ ซึ่งโดยทั่วไปจะเป็นหน่วยงานประเภทที่มีลำดับสูงสุด

LatLng

วัตถุที่แสดงคู่ละติจูด/ลองจิจูด ค่านี้จะแสดงเป็นเลขคู่เป็นเลขคู่ เพื่อแทนค่าองศาละติจูดและลองจิจูดองศา ออบเจ็กต์นี้ต้องเป็นไปตามมาตรฐาน WGS84 เว้นแต่จะระบุไว้เป็นอย่างอื่น ค่าต้องอยู่ภายในช่วงมาตรฐาน

ฟิลด์	ประเภท	คำอธิบาย
latitude	double	ละติจูดเป็นองศา ค่าต้องอยู่ในช่วง [-90.0, +90.0] เช่น 47.47583476464538
longitude	double	ลองจิจูด หน่วยเป็นองศา ค่าต้องอยู่ในช่วง [-180.0, +180.0] เช่น -121.73858779269906

รหัสข้อผิดพลาด

ค่า	คำอธิบาย
UnknownError	เกิดข้อผิดพลาดที่ไม่รู้จัก
NoMatchFound	ไม่พบคำขอที่ตรงกัน โปรดตรวจสอบ candidate_place_ids หากมี
AddressNotUnderstood	ระบุพิกัดทางภูมิศาสตร์ของที่อยู่ที่ระบุไม่สำเร็จ
PlaceTypeMismatch	ประเภทสถานที่ในการตอบกลับไม่ตรงกับคำขอ ตัวอย่างเช่น มีการขอ locality แต่มีการส่งเงินคืน administrative_area_level_2
MultipleCandidatesFound	มีการจับคู่กับตัวเลือกหลายรายการกับอินพุต โปรดตรวจสอบ candidate_place_ids หากมี
PlaceNameNotUnderstood	แก้ไขชื่อสถานที่ที่ระบุเป็นภูมิภาคไม่สำเร็จ
UnitCodeNotFound	ไม่พบรหัสหน่วย ตรวจสอบว่ารหัสหน่วยถูกต้องและระบุไว้ในรูปแบบที่ถูกต้อง
PlaceTypeNotAllowed	รหัสสถานที่ที่ตรงกันไม่ได้อยู่ในรายการที่อนุญาตของประเภทสถานที่และประเทศ