Method: places.autocomplete

แสดงผลการคาดการณ์สําหรับอินพุตที่ระบุ

คำขอ HTTP

POST https://places.googleapis.com/v1/places:autocomplete

URL ใช้ไวยากรณ์การแปลง gRPC

เนื้อหาของคำขอ

เนื้อความของคำขอมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string,
  "includePureServiceAreaBusinesses": boolean
}
ช่อง
input

string

ต้องระบุ สตริงข้อความที่จะค้นหา
locationBias

object (LocationBias)

ไม่บังคับ ปรับผลลัพธ์ให้เหมาะกับสถานที่ที่ระบุ

ควรตั้งค่า locationBias หรือ locationRestriction ไม่เกิน 1 รายการ หากไม่ได้ตั้งค่าทั้ง 2 อย่าง ผลลัพธ์จะมีความลำเอียงตามที่อยู่ IP ซึ่งหมายความว่าระบบจะแมปที่อยู่ IP กับตำแหน่งที่ไม่แม่นยำและใช้เป็นสัญญาณที่มีอคติ
locationRestriction

object (LocationRestriction)

ไม่บังคับ จำกัดผลการค้นหาให้แสดงเฉพาะสถานที่ที่ระบุ

ควรตั้งค่า locationBias หรือ locationRestriction ไม่เกิน 1 รายการ หากไม่ได้ตั้งค่าทั้ง 2 อย่าง ผลลัพธ์จะมีความลำเอียงตามที่อยู่ IP ซึ่งหมายความว่าระบบจะแมปที่อยู่ IP กับตำแหน่งที่ไม่แม่นยำและใช้เป็นสัญญาณที่มีอคติ
includedPrimaryTypes[]

string

ไม่บังคับ ประเภทสถานที่หลักที่รวมไว้ (เช่น "restaurant" หรือ "gas_station") ในประเภทสถานที่ (https://developers.google.com/maps/documentation/places/web-service/place-types) หรือเฉพาะ (regions) หรือเฉพาะ (cities) ระบบจะแสดงสถานที่ก็ต่อเมื่อประเภทหลักของสถานที่นั้นอยู่ในรายการนี้ โดยระบุได้สูงสุด 5 ค่า หากไม่ได้ระบุประเภท ระบบจะแสดงสถานที่ทุกประเภท
includedRegionCodes[]

string

ไม่บังคับ รวมเฉพาะผลการค้นหาในภูมิภาคที่ระบุ ซึ่งระบุเป็นรหัสภูมิภาค CLDR 2 อักขระได้สูงสุด 15 รหัส ชุดว่างจะไม่จํากัดผลลัพธ์ หากตั้งค่าทั้ง locationRestriction และ includedRegionCodes ไว้ ผลลัพธ์จะอยู่ในบริเวณที่ตัดกัน
languageCode

string

ไม่บังคับ ภาษาที่จะแสดงผลลัพธ์ ค่าเริ่มต้นคือ en-US ผลการค้นหาอาจมีทั้งภาษาไทยและอังกฤษหากภาษาที่ใช้ใน input แตกต่างจาก languageCode หรือหากสถานที่ที่แสดงไม่มีคำแปลจากภาษาท้องถิ่นเป็น languageCode
regionCode

string

ไม่บังคับ รหัสภูมิภาคที่ระบุเป็นรหัสภูมิภาค 2 อักขระ CLDR ซึ่งส่งผลต่อการจัดรูปแบบที่อยู่ การจัดอันดับผลการค้นหา และอาจส่งผลต่อผลการค้นหาที่แสดง ซึ่งจะไม่จำกัดผลการค้นหาให้แสดงเฉพาะในภูมิภาคที่ระบุ หากต้องการจำกัดผลการค้นหาให้แสดงเฉพาะในภูมิภาค ให้ใช้ region_code_restriction
origin

object (LatLng)

ไม่บังคับ จุดเริ่มต้นที่จะคำนวณระยะทางเชิงเรขาคณิตไปยังปลายทาง (แสดงผลเป็น distanceMeters) หากละเว้นค่านี้ ระบบจะไม่แสดงผลระยะทางเชิงเรขาคณิต
inputOffset

integer

ไม่บังคับ ออฟเซตอักขระ Unicode แบบนับจากศูนย์ของ input ที่ระบุตำแหน่งเคอร์เซอร์ใน input ตำแหน่งเคอร์เซอร์อาจส่งผลต่อผลการคาดการณ์ที่แสดง

หากเว้นว่างไว้ ระบบจะใช้ค่าเริ่มต้นเป็นความยาว input
includeQueryPredictions

boolean

ไม่บังคับ หากเป็น "จริง" การตอบกลับจะมีทั้งการคาดคะเนสถานที่และการคาดคะเนข้อความค้นหา มิเช่นนั้นการตอบกลับจะแสดงเฉพาะการคาดคะเนสถานที่
sessionToken

string

ไม่บังคับ สตริงที่ระบุเซสชันการเติมข้อความอัตโนมัติเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน ต้องเป็นสตริง Base64 ที่ปลอดภัยสำหรับ URL และชื่อไฟล์ซึ่งมีความยาวไม่เกิน 36 อักขระ ASCII ไม่เช่นนั้น ระบบจะแสดงข้อผิดพลาด INVALID_ARGUMENT

เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์ข้อความค้นหา และสิ้นสุดเมื่อผู้ใช้เลือกสถานที่และมีการเรียกใช้รายละเอียดสถานที่หรือการยืนยันที่อยู่ เซสชันแต่ละรายการอาจมีคำค้นหาหลายรายการ ตามด้วยคำขอรายละเอียดสถานที่หรือการยืนยันที่อยู่ 1 รายการ ข้อมูลเข้าสู่ระบบที่ใช้สำหรับคำขอแต่ละรายการภายในเซสชันต้องมาจากโปรเจ็กต์ Google Cloud Console เดียวกัน เมื่อเซสชันสิ้นสุดลง โทเค็นจะไม่มีผลอีกต่อไป แอปของคุณจึงต้องสร้างโทเค็นใหม่สำหรับแต่ละเซสชัน หากไม่ใส่พารามิเตอร์ sessionToken หรือคุณใช้โทเค็นเซสชันซ้ำ ระบบจะเรียกเก็บเงินสำหรับเซสชันนั้นราวกับว่าไม่ได้ระบุโทเค็นเซสชัน (ระบบจะเรียกเก็บเงินสำหรับคำขอแต่ละรายการแยกกัน)

เราขอแนะนำให้ทำตามหลักเกณฑ์ต่อไปนี้

  • ใช้โทเค็นเซสชันสำหรับการเรียกใช้ฟีเจอร์ป้อนข้อความอัตโนมัติของสถานที่ทั้งหมด
  • สร้างโทเค็นใหม่สำหรับเซสชันแต่ละรายการ ขอแนะนำให้ใช้ UUID เวอร์ชัน 4
  • ตรวจสอบว่าข้อมูลเข้าสู่ระบบที่ใช้สำหรับคำขอการเติมข้อความอัตโนมัติของสถานที่ รายละเอียดสถานที่ และการยืนยันที่อยู่ทั้งหมดภายในเซสชันเป็นของโปรเจ็กต์คอนโซลระบบคลาวด์เดียวกัน
  • อย่าลืมส่งโทเค็นเซสชันที่ไม่ซ้ำกันสำหรับเซสชันใหม่แต่ละรายการ การใช้โทเค็นเดียวกันในเซสชันมากกว่า 1 รายการจะทำให้มีการเรียกเก็บเงินสำหรับคำขอแต่ละรายการแยกกัน
includePureServiceAreaBusinesses

boolean

ไม่บังคับ รวมธุรกิจที่ให้บริการตามสถานที่เพียงอย่างเดียวหากตั้งค่าช่องเป็น "จริง" ธุรกิจที่ให้บริการตามสถานที่เพียงอย่างเดียวคือธุรกิจที่บริการแบบถึงที่หรือออกให้บริการแก่ลูกค้าโดยตรง โดยไม่ได้ให้บริการลูกค้า ณ ที่อยู่ธุรกิจ ตัวอย่างเช่น บริการทำความสะอาดหรือช่างประปา ธุรกิจเหล่านั้นไม่มีที่อยู่หรือสถานที่ตั้งจริงบน Google Maps โดย Places จะไม่แสดงฟิลด์ location, plusCode และฟิลด์อื่นๆ ที่เกี่ยวข้องกับสถานที่ตั้งสำหรับธุรกิจเหล่านี้

เนื้อหาการตอบกลับ

โปรโตคอลคำตอบสำหรับ places.autocomplete

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
ช่อง
suggestions[]

object (Suggestion)

มีรายการคำแนะนำที่จัดเรียงตามลำดับความเกี่ยวข้องจากมากไปน้อย

LocationBias

ภูมิภาคที่จะค้นหา ผลลัพธ์อาจเอนเอียงไปทางภูมิภาคที่ระบุ

การแสดง JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
ช่อง

ฟิลด์สหภาพ type

type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
rectangle

object (Viewport)

วิวพอร์ตที่กําหนดโดยมุมตะวันออกเฉียงเหนือและตะวันตกเฉียงใต้
circle

object (Circle)

วงกลมที่กําหนดโดยจุดศูนย์กลางและรัศมี

LocationRestriction

ภูมิภาคที่จะค้นหา ผลการค้นหาจะจํากัดเฉพาะภูมิภาคที่ระบุ

การแสดง JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
ช่อง

ฟิลด์สหภาพ type

type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
rectangle

object (Viewport)

วิวพอร์ตที่กําหนดโดยมุมตะวันออกเฉียงเหนือและตะวันตกเฉียงใต้
circle

object (Circle)

วงกลมที่กําหนดโดยจุดศูนย์กลางและรัศมี

คำแนะนำ

ผลการค้นหาของคำแนะนำที่เติมข้อความอัตโนมัติ

การแสดง JSON 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
ช่อง

ฟิลด์สหภาพ kind

kind ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้เท่านั้น
placePrediction

object (PlacePrediction)

การคาดการณ์สำหรับสถานที่
queryPrediction

object (QueryPrediction)

การคาดคะเนสําหรับคําค้นหา

PlacePrediction

ผลการคาดการณ์สําหรับการคาดคะเนการเติมข้อความอัตโนมัติของสถานที่

การแสดง JSON 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
ช่อง
place

string

ชื่อทรัพยากรของสถานที่ที่แนะนำ ชื่อนี้สามารถใช้ใน API อื่นๆ ที่ยอมรับชื่อสถานที่ได้
placeId

string

ตัวระบุที่ไม่ซ้ำกันของสถานที่ที่แนะนำ ตัวระบุนี้ใช้ได้ใน API อื่นๆ ที่ยอมรับรหัสสถานที่
text

object (FormattableText)

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

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

ข้อความนี้อาจแตกต่างจาก displayName ที่แสดงผลโดย places.get

อาจมีทั้งภาษาไทยและอังกฤษหากคำขอ input และ languageCode เป็นภาษาที่แตกต่างกัน หรือหากสถานที่ไม่มีคำแปลจากภาษาท้องถิ่นเป็น languageCode
structuredFormat

object (StructuredFormat)

รายละเอียดการคาดคะเนสถานที่เป็นข้อความหลักที่มีชื่อของสถานที่และข้อความรองที่มีสถานที่เพิ่มเติมที่จะช่วยคลายความกำกวม (เช่น เมืองหรือภูมิภาค)

เราขอแนะนำให้นักพัฒนาแอปใช้ structuredFormat หากต้องการแสดงองค์ประกอบ UI 2 รายการแยกกันแต่มีความเกี่ยวข้อง นักพัฒนาแอปที่ต้องการแสดงองค์ประกอบ UI รายการเดียวอาจต้องใช้ text แทน 2 วิธีนี้แสดงการคาดคะเนสถานที่ต่างกัน ผู้ใช้ไม่ควรพยายามแยกวิเคราะห์ structuredFormat เป็น text หรือในทางกลับกัน
types[]

string

รายการประเภทที่ใช้กับสถานที่นี้จากตาราง ก หรือตาราง ข ใน https://developers.google.com/maps/documentation/places/web-service/place-types

ประเภทคือการแบ่งหมวดหมู่ของสถานที่ สถานที่ที่มีประเภทร่วมกันจะมีลักษณะคล้ายกัน
distanceMeters

integer

ความยาวของเส้น geodesic เป็นเมตรจาก origin หากมีการระบุ origin การคาดการณ์บางอย่าง เช่น เส้นทาง อาจไม่แสดงในช่องนี้

FormattableText

ข้อความที่แสดงสถานที่หรือการคาดคะเนคำค้นหา โดยอาจใช้ข้อความตามที่เป็นอยู่หรือจัดรูปแบบก็ได้

การแสดง JSON 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
ช่อง
text

string

ข้อความที่อาจใช้ตามที่เป็นอยู่หรือจัดรูปแบบด้วย matches
matches[]

object (StringRange)

รายการช่วงสตริงที่ระบุตําแหน่งที่คำขออินพุตตรงกันใน text คุณสามารถใช้ช่วงเพื่อจัดรูปแบบบางส่วนของ text ได้ สตริงย่อยอาจไม่ตรงกันทุกประการกับ input หากการจับคู่นั้นพิจารณาจากเกณฑ์อื่นที่ไม่ใช่การจับคู่สตริง (เช่น การแก้ไขตัวสะกดหรือการถอดเสียง)

ค่าเหล่านี้คือออฟเซตอักขระ Unicode ของ text ระบบจะจัดเรียงช่วงตามค่าออฟเซ็ตที่เพิ่มขึ้น

StringRange

ระบุสตริงย่อยภายในข้อความที่ระบุ

การแสดง JSON 
{
  "startOffset": integer,
  "endOffset": integer
}
ช่อง
startOffset

integer

ส่วนเพิ่มแบบนับจาก 0 ของอักขระ Unicode ตัวแรกของสตริง (รวม)
endOffset

integer

ส่วนเพิ่มที่อิงจาก 0 ของอักขระ Unicode ตัวสุดท้าย (ไม่รวม)

StructuredFormat

มีรายละเอียดการคาดคะเนสถานที่หรือข้อความค้นหาเป็นข้อความหลักและข้อความรอง

สำหรับการคาดคะเนสถานที่ ข้อความหลักจะมีชื่อที่เฉพาะเจาะจงของสถานที่ สําหรับการคาดการณ์คําค้นหา ข้อความหลักจะมีคําค้นหา

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

การแสดง JSON 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
ช่อง
mainText

object (FormattableText)

แสดงชื่อสถานที่หรือการค้นหา
secondaryText

object (FormattableText)

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

QueryPrediction

ผลการคาดคะเนสําหรับการคาดคะเนการเติมข้อความอัตโนมัติ

การแสดง JSON 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
ช่อง
text

object (FormattableText)

ข้อความที่คาดคะเน ข้อความนี้ไม่ได้แสดงสถานที่ แต่เป็นข้อความค้นหาที่อาจใช้ในปลายทางการค้นหา (เช่น การค้นหาข้อความ)

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

อาจมีทั้งภาษาไทยและภาษาอังกฤษหากคำขอ input และ languageCode เป็นภาษาที่แตกต่างกัน หรือหากคำค้นหาบางส่วนไม่มีการแปลจากภาษาท้องถิ่นเป็น languageCode
structuredFormat

object (StructuredFormat)

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

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