เติมข้อความอัตโนมัติ (ใหม่)

บทนำ

การเติมข้อความอัตโนมัติ (ใหม่) เป็นเว็บเซอร์วิสที่แสดงการคาดคะเนสถานที่และการคาดคะเนคำค้นหาเพื่อตอบสนองต่อคำขอ HTTP ในคำขอ ให้ระบุสตริงการค้นหาข้อความและขอบเขตทางภูมิศาสตร์ที่ควบคุมพื้นที่การค้นหา

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

การตอบกลับจากการเติมข้อความอัตโนมัติ (ใหม่) อาจมีการคาดคะเน 2 ประเภท ได้แก่

• การคาดคะเนสถานที่: สถานที่ เช่น ธุรกิจ ที่อยู่ และจุดที่น่าสนใจ โดยอิงตามสตริงข้อความที่ป้อนและพื้นที่ค้นหาที่ระบุ ระบบจะแสดงการคาดคะเนสถานที่โดยค่าเริ่มต้น
• การคาดการณ์คำค้นหา: สตริงคำค้นหาที่ตรงกับสตริงข้อความที่ป้อนและ พื้นที่ค้นหา ระบบจะไม่แสดงการคาดการณ์การค้นหาโดยค่าเริ่มต้น ใช้พารามิเตอร์คำขอ includeQueryPredictions เพื่อเพิ่มการคาดการณ์การค้นหาในการตอบกลับ

ตัวอย่างเช่น คุณเรียกใช้การเติมข้อความอัตโนมัติ (ใหม่) โดยใช้สตริงที่มีข้อมูลจากผู้ใช้บางส่วนเป็นอินพุต เช่น "Sicilian piz" โดยจำกัดพื้นที่ค้นหาไว้ที่ซานฟรานซิสโก แคลิฟอร์เนีย จากนั้นคำตอบจะมีรายการการคาดคะเนสถานที่ที่ตรงกับสตริงการค้นหาและพื้นที่ค้นหา เช่น ร้านอาหารชื่อ "Sicilian Pizza Kitchen" พร้อมรายละเอียดเกี่ยวกับสถานที่

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

การตอบกลับยังอาจมีรายการการคาดคะเนการค้นหาที่ตรงกับสตริงการค้นหาและพื้นที่การค้นหา เช่น "Sicilian Pizza & Pasta" การคาดคะเนการค้นหาแต่ละรายการในการตอบกลับจะมีช่อง text ซึ่งมีสตริงการค้นหาข้อความที่แนะนำ ใช้สตริงดังกล่าวเป็นอินพุตไปยังการค้นหาข้อความ (ใหม่) เพื่อทำการค้นหาที่ละเอียดยิ่งขึ้น

โปรแกรมสำรวจ API ช่วยให้คุณส่งคำขอแบบสดเพื่อให้คุ้นเคยกับ API และตัวเลือก API ได้

คำขอเติมข้อความอัตโนมัติ (ใหม่)

คำขอการเติมข้อความอัตโนมัติ (ใหม่) คือคำขอ POST ไปยัง URL ในรูปแบบต่อไปนี้

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

ส่งพารามิเตอร์ทั้งหมดในเนื้อหาคำขอ JSON หรือในส่วนหัวโดยเป็นส่วนหนึ่งของคำขอ POST เช่น

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

พารามิเตอร์ที่รองรับ

เกี่ยวกับคำตอบ

ฟีเจอร์เติมข้อความอัตโนมัติ (ใหม่) จะแสดงผลออบเจ็กต์ JSON เป็นการตอบกลับ ในการตอบกลับ ให้ทำดังนี้

• อาร์เรย์ suggestions มีสถานที่และคำค้นหาที่คาดการณ์ทั้งหมดตามลำดับ โดยอิงตามความเกี่ยวข้องที่รับรู้ สถานที่แต่ละแห่งจะแสดงด้วยช่อง placePrediction และคำค้นหาแต่ละรายการจะแสดงด้วยช่อง queryPrediction
• ช่อง placePrediction มีข้อมูลโดยละเอียดเกี่ยวกับการคาดคะเนสถานที่รายการเดียว ซึ่งรวมถึงรหัสสถานที่และคำอธิบายข้อความ
  • คำอธิบายข้อความของการคาดคะเนสถานที่อาจมีชื่ออื่นของสถานที่ ถนน และองค์ประกอบอื่นๆ ของที่อยู่ เพื่อให้ตรงกับข้อมูลที่ผู้ใช้ป้อนตามที่ระบุไว้ในพารามิเตอร์ input มากขึ้น ชื่ออื่นเหล่านี้อาจแตกต่างจากชื่อที่แสดงในฟิลด์ displayName และฟิลด์ที่อยู่ของผลลัพธ์รายละเอียดสถานที่สำหรับรหัสสถานที่เดียวกัน
  • ในบริบทนี้ ชื่ออื่นของสถานที่บางแห่งอาจเป็นภาษาอื่นนอกเหนือจากที่คาดไว้ตามพารามิเตอร์ languageCode โดยขึ้นอยู่กับว่าชื่อใดตรงกับข้อมูลจากผู้ใช้มากกว่า
• queryPrediction ฟิลด์มีข้อมูลโดยละเอียดเกี่ยวกับการคาดคะเนการค้นหาเดียว

ออบเจ็กต์ JSON ที่สมบูรณ์จะอยู่ในรูปแบบดังนี้

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

พารามิเตอร์ที่จำเป็น

• อินพุต

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

พารามิเตอร์ที่ไม่บังคับ

• FieldMask

  ระบุรายการฟิลด์ที่จะแสดงในคำตอบโดยสร้างมาสก์ฟิลด์คำตอบ ส่งมาสก์ฟิลด์การตอบกลับไปยังเมธอดโดยใช้ส่วนหัว HTTP X-Goog-FieldMask

  ระบุรายการช่องคำแนะนำที่คั่นด้วยคอมมาที่จะแสดงผล เช่น เพื่อดึงข้อมูล suggestions.placePrediction.text.text และ suggestions.queryPrediction.text.text ของคำแนะนำ

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  ใช้ * เพื่อดึงข้อมูลทุกฟิลด์

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

  หาก true, แสดงธุรกิจ ที่คาดว่าจะเปิดในอนาคต ค่าเริ่มต้นคือ false

• includedPrimaryTypes

  สถานที่หนึ่งๆ จะมีประเภทหลักเดียวจากประเภทที่แสดงใน ตาราง A หรือ ตาราง B ได้เท่านั้น เช่น ประเภทหลักอาจเป็น "mexican_restaurant" หรือ "steak_house"

  โดยค่าเริ่มต้น API จะแสดงสถานที่ทั้งหมดตามพารามิเตอร์ input โดยไม่คำนึงถึงค่าประเภทหลักที่เชื่อมโยงกับสถานที่ จำกัดผลลัพธ์ให้เป็นประเภทหลักที่เฉพาะเจาะจง หรือประเภทหลักโดยส่งพารามิเตอร์ includedPrimaryTypes

  ใช้พารามิเตอร์นี้เพื่อระบุค่าประเภทได้สูงสุด 5 ค่าจาก ตาราง A หรือ ตาราง B สถานที่ต้องตรงกับค่าประเภทหลักที่ระบุค่าใดค่าหนึ่งจึงจะรวมอยู่ในการตอบกลับ

  พารามิเตอร์นี้อาจมี (regions) หรือ (cities) แทนก็ได้ (regions) ตัวกรองคอลเล็กชันประเภทสำหรับพื้นที่หรือ เขต เช่น ย่านและรหัสไปรษณีย์ (cities) คอลเล็กชันประเภท กรองสถานที่ที่ Google ระบุว่าเป็นเมือง

  คำขอจะถูกปฏิเสธพร้อมข้อผิดพลาด INVALID_REQUEST ในกรณีต่อไปนี้

  • ระบุประเภทมากกว่า 5 ประเภท
  • มีการระบุประเภทใดก็ตามนอกเหนือจาก (cities) หรือ (regions)
  • ระบุประเภทที่ไม่รู้จัก

• includePureServiceAreaBusinesses

  หากตั้งค่าเป็น true การตอบกลับจะรวมธุรกิจที่เข้าพบหรือนำส่งสินค้าให้ลูกค้าโดยตรง แต่ไม่มีที่ตั้งธุรกิจจริง หากตั้งค่าเป็น false API จะแสดงเฉพาะธุรกิจที่มี สถานที่ตั้งจริง

• includeQueryPredictions

  หากเป็น true การตอบกลับจะมีทั้งการคาดคะเนสถานที่และการคาดคะเนการค้นหา ค่าเริ่มต้น คือ false ซึ่งหมายความว่าการตอบกลับจะมีเฉพาะการคาดคะเนสถานที่

• includedRegionCodes

  รวมเฉพาะผลลัพธ์จากรายการภูมิภาคที่ระบุ ซึ่งระบุเป็นอาร์เรย์ของค่า ccTLD ("โดเมนระดับบนสุด") 2 อักขระสูงสุด 15 ค่า หากละเว้น ระบบจะไม่ใช้ข้อจำกัดใดๆ กับการตอบกลับ เช่น หากต้องการจำกัดภูมิภาคเป็นเยอรมนีและฝรั่งเศส ให้ทำดังนี้

      "includedRegionCodes": ["de", "fr"]

  หากคุณระบุทั้ง locationRestriction และ includedRegionCodes ผลลัพธ์จะอยู่ในพื้นที่ที่การตั้งค่าทั้ง 2 รายการตัดกัน

• inputOffset

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

• languageCode

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

  • คุณต้องใช้รหัสภาษา IETF BCP-47 เพื่อระบุภาษาที่ต้องการ
  • หากไม่ได้ระบุ languageCode API จะใช้ค่าที่ระบุในส่วนหัว Accept-Language หากไม่ได้ระบุทั้ง 2 อย่าง ค่าเริ่มต้นจะเป็น en หากคุณระบุรหัสภาษาที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาด INVALID_ARGUMENT
  • ภาษาที่ต้องการมีผลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกที่จะแสดง และลำดับที่แสดง ซึ่งจะส่งผลต่อความสามารถของ API ในการแก้ไขข้อผิดพลาดในการสะกดด้วย
  • ระบบจะจัดรูปแบบการคาดคะเนสถานที่แตกต่างกันไปตามข้อมูลที่ผู้ใช้ป้อนในแต่ละคำขอ
    • ระบบจะเลือกคำที่ตรงกันในพารามิเตอร์ input ก่อน โดยใช้ชื่อที่สอดคล้องกับค่ากำหนดภาษาที่ระบุโดยพารามิเตอร์ languageCode (หากมี) หรือใช้ชื่อที่ตรงกับข้อมูลจากผู้ใช้มากที่สุด
    • คุณอาจจัดรูปแบบชื่อสถานที่โดยใช้ชื่ออื่นเพื่อให้ตรงกับ ข้อกำหนดในพารามิเตอร์ input ซึ่งรวมถึงชื่อใน ภาษาอื่นๆ นอกเหนือจากภาษาที่ระบุโดยพารามิเตอร์ languageCode
    • ระบบจะจัดรูปแบบที่อยู่เป็นภาษาท้องถิ่นในสคริปต์ที่ผู้ใช้อ่านได้ เมื่อเป็นไปได้ หลังจากเลือกคำที่ตรงกันให้ตรงกับคำในพารามิเตอร์ input เท่านั้น
    • ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการหลังจากเลือกคำที่ตรงกันแล้ว เพื่อให้ตรงกับคำในพารามิเตอร์ input หากชื่อไม่มีในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด

• locationBias หรือ locationRestriction

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

  • locationBias

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

  • locationRestriction

    ระบุพื้นที่ที่จะค้นหา ระบบจะไม่แสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่ระบุ

  ระบุภูมิภาค locationBias หรือ locationRestriction เป็นวิวพอร์ตสี่เหลี่ยมผืนผ้าหรือเป็นวงกลม

  • วงกลมกำหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 (รวม) ค่าเริ่มต้นคือ 0.0 สำหรับ locationRestriction คุณต้องตั้งค่ารัศมีให้มากกว่า 0.0 ไม่เช่นนั้น คำขอจะแสดงผลเป็น ไม่มีผลลัพธ์

    เช่น

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • สี่เหลี่ยมผืนผ้าคือวิวพอร์ตในรูปแบบละติจูด-ลองจิจูด ซึ่งกำหนดด้วยจุดสองจุดที่อยู่มุมตรงข้ามกัน โดยจุดหนึ่งเป็นค่าต่ำสุดlowและอีกจุดเป็นค่าสูงสุด วิวพอร์ตถือเป็นพื้นที่ปิด ซึ่งหมายรวมถึงขอบเขตของตัววิวพอร์ตเองด้วย ขอบเขตละติจูด ต้องอยู่ระหว่าง -90 ถึง 90 องศา และขอบเขตลองจิจูด ต้องอยู่ระหว่าง -180 ถึง 180 องศา

    • หาก low = high วิวพอร์ตจะประกอบด้วยจุดเดียว
    • หาก low.longitude > high.longitude หมายความว่าช่วงลองจิจูดกลับด้าน (วิวพอร์ตข้ามเส้นลองจิจูด 180 องศา)
    • หาก low.longitude = -180 องศา และ high.longitude = 180 องศา วิวพอร์ตจะครอบคลุมลองจิจูดทั้งหมด
    • หาก low.longitude = 180 องศา และ high.longitude = -180 องศา ช่วงลองจิจูดจะว่างเปล่า

    คุณต้องระบุทั้ง low และ high และช่องที่แสดงต้องไม่ว่าง เนื่องจากวิวพอร์ตที่ว่างเปล่าจะทำให้เกิดข้อผิดพลาด

    ตัวอย่างเช่น วิวพอร์ตนี้ครอบคลุมนิวยอร์กซิตี้ทั้งหมด

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• origin

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

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

  รหัสภูมิภาคที่ใช้จัดรูปแบบการตอบกลับ โดยระบุเป็นค่า 2 อักขระของ ccTLD ("โดเมนระดับบนสุด") รหัส ccTLD ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นที่สำคัญบางประการ ตัวอย่างเช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ขณะที่รหัส ISO 3166-1 คือ "gb" (ในทางเทคนิคสำหรับ นิติบุคคล "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ")

  นอกจากนี้ คำแนะนำยังอาจเอนเอียงตามรหัสภูมิภาคด้วย Google ขอแนะนำให้ตั้งค่า regionCode ตามค่ากำหนดตามพื้นที่ของผู้ใช้

  หากคุณระบุรหัสภูมิภาคที่ไม่ถูกต้อง API จะแสดงข้อผิดพลาด INVALID_ARGUMENT พารามิเตอร์นี้อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้อง

• sessionToken

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

เลือกพารามิเตอร์เพื่อให้น้ำหนักผลลัพธ์

ตัวอย่างการเติมข้อความอัตโนมัติ (ใหม่)

จำกัดการค้นหาในพื้นที่โดยใช้ locationRestriction

locationRestriction ระบุพื้นที่ที่จะค้นหา ระบบจะไม่แสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่ระบุ ในตัวอย่างต่อไปนี้ คุณใช้ locationRestriction เพื่อจำกัดคำขอให้เป็นวงกลมที่มีรัศมี 5, 000 เมตรซึ่งมีจุดศูนย์กลางอยู่ที่ซานฟรานซิสโก

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

ผลลัพธ์ทั้งหมดจากภายในพื้นที่ที่ระบุจะอยู่ในอาร์เรย์ suggestions

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

นอกจากนี้ คุณยังใช้ locationRestriction เพื่อจำกัดการค้นหาให้แสดงเฉพาะในสี่เหลี่ยมผืนผ้า Viewport ได้ด้วย ตัวอย่างต่อไปนี้จำกัดคำขอไว้ที่ตัวเมืองซานฟรานซิสโก

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

ผลลัพธ์จะอยู่ในอาร์เรย์ suggestions ดังนี้

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

กำหนดการค้นหาไปยังพื้นที่โดยใช้ locationBias

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

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

ตอนนี้ผลการค้นหามีรายการมากขึ้น รวมถึงผลการค้นหาที่อยู่นอกรัศมี 5, 000 เมตรด้วย

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

นอกจากนี้ คุณยังใช้ locationBias เพื่อให้การค้นหามุ่งเน้นไปที่สี่เหลี่ยมผืนผ้า Viewport ได้ด้วย ตัวอย่างต่อไปนี้จำกัดคำขอไว้ที่ตัวเมืองซานฟรานซิสโก

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

แม้ว่าผลการค้นหาภายในวิวพอร์ตสี่เหลี่ยมผืนผ้าจะปรากฏในการตอบกลับ แต่ผลการค้นหาบางรายการอยู่นอกขอบเขตที่กำหนดเนื่องจากการให้น้ำหนักพิเศษ ผลลัพธ์จะอยู่ในอาร์เรย์ suggestions ด้วย

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

ใช้ includedPrimaryTypes

ใช้พารามิเตอร์ includedPrimaryTypes เพื่อระบุค่าประเภทได้สูงสุด 5 ค่าจาก ตาราง ก ตาราง ข หรือ (regions) เท่านั้น หรือ (cities) เท่านั้น สถานที่ต้องตรงกับค่าประเภทหลักที่ระบุค่าใดค่าหนึ่งจึงจะรวมอยู่ในการตอบกลับ

ในตัวอย่างต่อไปนี้ คุณระบุสตริง input เป็น "Soccer" และใช้พารามิเตอร์ includedPrimaryTypes เพื่อจำกัดผลลัพธ์ให้แสดงเฉพาะสถานที่ประเภท "sporting_goods_store"

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

หากไม่ใส่พารามิเตอร์ includedPrimaryTypes ผลลัพธ์อาจรวมถึงสถานประกอบการประเภทที่คุณไม่ต้องการ เช่น "athletic_field"

ขอการคาดคะเนคำค้นหา

ระบบจะไม่แสดงการคาดการณ์การค้นหาโดยค่าเริ่มต้น ใช้พารามิเตอร์คำขอ includeQueryPredictions เพื่อเพิ่มการคาดคะเนการค้นหาลงในการตอบกลับ เช่น

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

ตอนนี้อาร์เรย์ suggestions มีทั้งการคาดคะเนสถานที่และการคาดคะเนการค้นหาตามที่แสดงด้านบนในเกี่ยวกับการตอบกลับ การคาดการณ์การค้นหาแต่ละรายการ มีฟิลด์ text ที่มีสตริงการค้นหาข้อความที่แนะนำ คุณสามารถส่งคำขอการค้นหาข้อความ (ใหม่) เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการคาดคะเนคำค้นหาที่แสดงผลได้

ใช้ต้นทาง

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

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

ตอนนี้คำตอบจะมีdistanceMetersดังนี้

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

ค้นหาธุรกิจที่จะเปิดในอนาคต

ตัวอย่างต่อไปนี้แสดงคำขอการเติมข้อความอัตโนมัติ (ใหม่) สำหรับธุรกิจที่กำลังจะเปิดในอนาคตในเมืองนิวเมโดวส์ รัฐไอดาโฮ

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

การตอบกลับจะมีรายละเอียดเกี่ยวกับสถานที่ แต่ไม่มีวันที่เปิด

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

ไม่มีระยะทางในการตอบกลับ

ในบางกรณี distanceMeters จะหายไปจากเนื้อหาการตอบกลับ แม้ว่า origin จะรวมอยู่ในคำขอก็ตาม ซึ่งอาจเกิดขึ้นในสถานการณ์ต่อไปนี้

• distanceMeters ไม่รวมอยู่ในการคาดการณ์ route
• distanceMeters จะไม่รวมอยู่ด้วยเมื่อค่าเป็น 0 ซึ่งเป็นกรณีของการคาดคะเนที่อยู่ห่างจากตำแหน่ง origin ที่ระบุน้อยกว่า 1 เมตร

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

การเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติ (ใหม่)

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

หลักเกณฑ์ทั่วไปมีดังนี้

• วิธีที่รวดเร็วที่สุดในการพัฒนาอินเทอร์เฟซผู้ใช้ที่ใช้งานได้คือการใช้วิดเจ็ตการเติมข้อความอัตโนมัติ (ใหม่) ของ Maps JavaScript API, วิดเจ็ตการเติมข้อความอัตโนมัติ (ใหม่) ของ Places SDK สำหรับ Android หรือวิดเจ็ตการเติมข้อความอัตโนมัติ (ใหม่) ของ Places SDK สำหรับ iOS
• ทำความเข้าใจฟิลด์ข้อมูลที่จำเป็น การเติมข้อความอัตโนมัติ (ใหม่) ตั้งแต่เริ่มต้น
• ช่องการให้น้ำหนักตามสถานที่และการจำกัดสถานที่ตั้งเป็นช่องที่ไม่บังคับ แต่ก็อาจส่งผลต่อประสิทธิภาพการเติมข้อความอัตโนมัติอย่างมาก
• ใช้การจัดการข้อผิดพลาดเพื่อให้แน่ใจว่าแอปจะลดระดับลงอย่างราบรื่นหาก API แสดงข้อผิดพลาด
• ตรวจสอบว่าแอปของคุณจัดการกรณีที่ไม่มีการเลือกและเสนอวิธีให้ผู้ใช้ดำเนินการต่อ

แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพต้นทุน

การเพิ่มประสิทธิภาพต้นทุนขั้นพื้นฐาน

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

การเพิ่มประสิทธิภาพต้นทุนขั้นสูง

พิจารณาการใช้งาน Autocomplete (ใหม่) แบบเป็นโปรแกรมเพื่อเข้าถึง SKU: ราคาคำขอเติมข้อความอัตโนมัติ และขอผลลัพธ์ Geocoding API เกี่ยวกับสถานที่ที่เลือกแทนรายละเอียดสถานที่ (ใหม่) การกำหนดราคาต่อคำขอที่ใช้ร่วมกับ Geocoding API จะคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน (อิงตามเซสชัน) หากเป็นไปตามเงื่อนไขต่อไปนี้ทั้ง 2 ข้อ

• หากต้องการเพียงละติจูดและลองจิจูดหรือที่อยู่ของสถานที่ที่ผู้ใช้เลือก Geocoding API จะให้ข้อมูลนี้โดยมีค่าใช้จ่ายน้อยกว่าการเรียกใช้รายละเอียดสถานที่ (ใหม่)
• หากผู้ใช้เลือกการคาดคะเนการเติมข้อความอัตโนมัติภายในคำขอการคาดคะเนการเติมข้อความอัตโนมัติ (ใหม่) โดยเฉลี่ย 4 รายการหรือน้อยกว่า การกำหนดราคาต่อคำขออาจคุ้มค่ากว่าการกำหนดราคาต่อเซสชัน

แอปพลิเคชันของคุณต้องใช้ข้อมูลอื่นนอกเหนือจากที่อยู่และละติจูด/ลองจิจูดของการคาดการณ์ที่เลือกไหม

แนวทางปฏิบัติแนะนำด้านประสิทธิภาพ

หลักเกณฑ์ต่อไปนี้อธิบายวิธีเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติ (ใหม่)

• เพิ่มข้อจำกัดในแต่ละประเทศ การเอนเอียงตามสถานที่ตั้ง และ (สำหรับการติดตั้งใช้งานแบบเป็นโปรแกรม) ค่ากำหนดภาษาลงในการติดตั้งใช้งานการเติมข้อความอัตโนมัติ (ใหม่) ไม่จำเป็นต้องใช้ค่ากำหนดภาษาสำหรับวิดเจ็ต เนื่องจากวิดเจ็ตจะเลือกค่ากำหนดภาษาจากเบราว์เซอร์หรืออุปกรณ์เคลื่อนที่ของผู้ใช้
• หากการเติมข้อความอัตโนมัติ (ใหม่) มาพร้อมกับแผนที่ คุณสามารถกำหนดตำแหน่งตามวิวพอร์ตของแผนที่ได้
• ในกรณีที่ผู้ใช้ไม่ได้เลือกการคาดคะเนการเติมข้อความอัตโนมัติ (ใหม่) รายการใดรายการหนึ่ง โดยทั่วไป เนื่องจากการคาดคะเนเหล่านั้นไม่ใช่ผลลัพธ์ที่ผู้ใช้ต้องการ คุณสามารถนำข้อมูลจากผู้ใช้เดิมมาใช้ซ้ำเพื่อพยายามรับผลลัพธ์ที่เกี่ยวข้องมากขึ้นได้โดยทำดังนี้
  • หากคาดหวังให้ผู้ใช้ป้อนเฉพาะข้อมูลที่อยู่ ให้นำข้อมูลที่ผู้ใช้ป้อนเดิมมาใช้ซ้ำ ในการเรียก Geocoding API
  • หากคาดว่าผู้ใช้จะป้อนคำค้นหาสถานที่ที่เฉพาะเจาะจงตามชื่อหรือที่อยู่ ให้ใช้คำขอรายละเอียดสถานที่ (ใหม่) หากคาดหวังผลลัพธ์ในภูมิภาคที่เฉพาะเจาะจงเท่านั้น ให้ใช้การเอนเอียงตามตำแหน่ง
  สถานการณ์อื่นๆ ที่ควรเปลี่ยนไปใช้ Geocoding API ได้แก่
  • ผู้ใช้ที่ป้อนที่อยู่ย่อย เช่น ที่อยู่สำหรับยูนิตหรืออพาร์ตเมนต์ที่เฉพาะเจาะจง ภายในอาคาร เช่น ที่อยู่ในสาธารณรัฐเช็ก "Stroupežnického 3191/17, Praha" จะแสดงการคาดคะเนบางส่วนในการเติมข้อความอัตโนมัติ (ใหม่)
  • ผู้ใช้ที่ป้อนที่อยู่ที่มีคำนำหน้าส่วนของถนน เช่น "23-30 29th St, Queens" ใน นิวยอร์กซิตี้ หรือ "47-380 Kamehameha Hwy, Kaneohe" บนเกาะคาไวในฮาวาย

การให้น้ำหนักพิเศษกับบางตำแหน่ง

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

การจำกัดตำแหน่ง

จำกัดผลการค้นหาให้อยู่ในพื้นที่ที่ระบุโดยส่งพารามิเตอร์ locationRestriction

นอกจากนี้ คุณยังจำกัดผลลัพธ์ให้แสดงเฉพาะภูมิภาคที่กำหนดโดย location และพารามิเตอร์ radius ได้ด้วยโดยการเพิ่มพารามิเตอร์ locationRestriction ซึ่งจะสั่งให้การเติมข้อความอัตโนมัติ (ใหม่) แสดงเฉพาะ ผลลัพธ์ภายในภูมิภาคนั้น

ลองใช้งาน

โปรแกรมสำรวจ API ช่วยให้คุณสร้างคำขอตัวอย่างเพื่อให้คุ้นเคยกับ API และตัวเลือก API

1. เลือกไอคอน API api ทางด้านขวาของหน้า

2. แก้ไขพารามิเตอร์คำขอ (ไม่บังคับ)

3. เลือกปุ่มดำเนินการ ในกล่องโต้ตอบ ให้เลือกบัญชี ที่ต้องการใช้เพื่อส่งคำขอ

4. ในแผงโปรแกรมสำรวจ API ให้เลือกไอคอนเต็มหน้าจอ fullscreen เพื่อขยายหน้าต่างโปรแกรมสำรวจ API