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
}
ช่อง
input

string

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

object (LocationBias)

ไม่บังคับ การให้น้ำหนักผลลัพธ์กับตำแหน่งที่ระบุ

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

object (LocationRestriction)

ไม่บังคับ จำกัดผลลัพธ์ไปยังตำแหน่งที่ระบุ

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

string

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

string

ไม่บังคับ รวมเฉพาะผลลัพธ์ในภูมิภาคที่ระบุ โดยระบุเป็นรหัสภูมิภาคแบบ 2 อักขระสำหรับ CLDR สูงสุด 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 และชื่อไฟล์ที่ปลอดภัยและมีอักขระ ASCII ไม่เกิน 36 ตัว มิฉะนั้น ระบบจะแสดงข้อผิดพลาด INVALID_ARGUMENT

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

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

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

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

โปรโตคอลการตอบกลับสำหรับ 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

ความยาวของเรขาคณิตมีหน่วยเป็นเมตรจาก 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

ออฟเซ็ตแบบศูนย์ของอักขระ Unicode ตัวแรกของสตริง (รวม)
endOffset

integer

ออฟเซ็ตแบบศูนย์ของอักขระ 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 หรือในทางกลับกัน