ใช้ Region Lookup API

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

  • การค้นหาภูมิภาคจะค้นหาภูมิภาคตามชื่อสถานที่, รหัส FIPS (รัฐและเทศมณฑลในสหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ ISO-3166-1
  • การค้นหาภูมิภาคจะค้นหาภูมิภาคที่มีสถานที่ตั้งที่เฉพาะเจาะจงตามที่ระบุไว้ในที่อยู่ LatLng หรือรหัสสถานที่

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

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

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

หากต้องการใช้ Region Lookup API ให้ทำตามขั้นตอนต่อไปนี้

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

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

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

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

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

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

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

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

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

  • place หรือ unit_code (ต้องระบุ) ชื่อภูมิภาค (place) หรือ unit_code ของสถานที่ unit_code อาจเป็นรหัส FIPS (รัฐและเขตของสหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ ISO-3166-1 ก็ได้
  • place_type (ต้องระบุ) ค่าประเภทสถานที่สำหรับประเภทสถานที่ที่จะค้นหา
  • region_code รหัสประเทศ/ภูมิภาค ISO-3166 แบบ 2 ตัวอักษรสำหรับสถานที่ตั้งที่ต้องการจับคู่ 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 คือ "California" และ place_type คือ ADMINISTRATIVE_AREA_LEVEL_1 API จะแสดงรหัสสถานที่ของ California เป็น 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 คือ "Santa Clara County" และ place_type คือ LOCALITY ระบบจะแสดงรหัสสถานที่ของ Santa Clara County เป็นตัวเลือก

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

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

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

คำขอค้นหาเฉพาะส่วน

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

  • address หรือ latlng หรือ place_id (ต้องระบุ) มีสตริงที่อยู่ที่ไม่มีโครงสร้าง latlng หรือรหัสสถานที่ที่อยู่ในภูมิภาค (เช่น จุดที่น่าสนใจ อาคาร และอื่นๆ) หากไม่ระบุ ระบบจะแสดงผลข้อผิดพลาด
  • place_type (ต้องระบุ) ค่า place type สำหรับประเภทภูมิภาคที่จะค้นหา
  • region_code รหัสประเทศ/ภูมิภาค ISO-3166 แบบ 2 ตัวอักษรสำหรับสถานที่ตั้งที่ต้องการจับคู่ ต้องระบุ 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 สตริง ชื่อภูมิภาคที่จะจับคู่กับรหัสสถานที่ ใช้ช่อง place ร่วมกับ place_type เพื่อค้นหารหัสสถานที่ของภูมิภาค เช่น หาก place_type คือ "locality" ค่า place ที่ถูกต้องอาจเป็น "Palo Alto, CA" หาก place_type เป็น `POSTAL_CODE` ค่า place_name ที่ถูกต้องอาจเป็น "94109" หาก place_type เป็น `COUNTRY` ค่า place ที่ถูกต้องอาจเป็น "สหรัฐอเมริกา" เป็นต้น ต้องระบุ region_code เมื่อมีการระบุ place เว้นแต่ place_type จะเป็น `COUNTRY`
unit_code สตริง รหัสรัฐหรือรหัสเขต FIP (สหรัฐอเมริกาเท่านั้น) หรือรหัสประเทศ 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" (รหัส FIPs สำหรับแคลิฟอร์เนีย) หรือ "12"(รหัส FIPs สำหรับฟลอริดา) หาก place_type คือ ADMINISTRATIVE_AREA_LEVEL_2 (เขต) และ region_code คือ "US" ค่า unit_code ที่ถูกต้องอาจเป็น "6001" (รหัส FIPs สำหรับเขตอลาเมดาในแคลิฟอร์เนีย) หรือ "12086" (รหัส FIPs สำหรับเขตไมแอมี-เดดในฟลอริดา) ต้องระบุ region_code เมื่อระบุรหัส FIP ระบบจะละเว้น region_code สำหรับรหัสประเทศ ISO-3166-1
place_type PlaceType ต้องระบุ ประเภทของภูมิภาคที่จะจับคู่
region_code สตริง รหัสประเทศ/ภูมิภาค ISO-3166 แบบ 2 ตัวอักษรสำหรับสถานที่ตั้งที่คุณพยายามจับคู่ region_code จะไม่บังคับหาก place_type เป็น `COUNTRY`
language_code สตริง รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" ที่สอดคล้องกับภาษาที่ใช้ขอชื่อและที่อยู่ของสถานที่ หากไม่ได้ขอภาษาใด ระบบจะใช้ภาษาอังกฤษเป็นค่าเริ่มต้น

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

ต้องระบุ: address, latlng หรือ place_id อย่างใดอย่างหนึ่ง

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

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

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

LatLng

ออบเจ็กต์ที่แสดงคู่ละติจูด/ลองจิจูด ซึ่งจะแสดงเป็นคู่ของค่า Double เพื่อแสดงองศาละติจูดและองศาลองจิจูด ออบเจ็กต์นี้ต้องเป็นไปตามมาตรฐาน 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 รหัสสถานที่ที่ตรงกันไม่อยู่ในรายการที่อนุญาตของประเภทสถานที่และประเทศ