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,
  "includeFutureOpeningBusinesses": boolean
}
ช่อง
input

string

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

object (LocationBias)

ไม่บังคับ เอนเอียงผลลัพธ์ไปยังสถานที่ที่ระบุ

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

object (LocationRestriction)

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

ควรตั้งค่า locationBias หรือ locationRestriction อย่างใดอย่างหนึ่งเท่านั้น หากไม่ได้ตั้งค่าทั้ง 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

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

object (LatLng)

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

integer

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

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

boolean

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

string

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

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

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

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

boolean

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

boolean

ไม่บังคับ หากเป็นจริง ให้รวมธุรกิจที่ยังไม่เปิดทำการแต่จะเปิดในอนาคต

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

Proto ของการตอบกลับสำหรับ places.autocomplete

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

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

object (Suggestion)

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

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth ต่อไปนี้

  • https://www.googleapis.com/auth/cloud-platform

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

ฟิลด์ Union 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.
}
ช่อง

ฟิลด์ Union 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.
}
ช่อง

ฟิลด์ Union kind

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

object (PlacePrediction)

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

object (QueryPrediction)

การคาดการณ์สำหรับคำค้นหา

PlacePrediction

ผลการคาดการณ์สำหรับการคาดการณ์ Place Autocomplete

การแสดง 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

รายการประเภทที่ใช้กับสถานที่นี้จากตาราง A หรือตาราง B ใน 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

ออฟเซ็ตแบบอิงตาม 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 หรือในทางกลับกัน