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

บทนำ

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

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

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

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

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

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

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

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

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

คำขอการเติมข้อความอัตโนมัติ (ใหม่) คือคำขอ HTTP 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 ฟิลด์มีข้อมูลโดยละเอียดเกี่ยวกับการคาดคะเนสถานที่เดียว รวมถึงรหัสสถานที่และคำอธิบายข้อความ
• 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 Codes บริการเติมข้อความอัตโนมัติ (ใหม่) จะแสดงรายการที่ตรงกันตามสตริงนี้และจัดลำดับผลลัพธ์ตาม ความเกี่ยวข้องที่รับรู้

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

• 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: *

• includedPrimaryTypes

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

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

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

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

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

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

• includePureServiceAreaBusinesses

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

• includeQueryPredictions

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

• includedRegionCodes

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

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

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

• inputOffset

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

• languageCode

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

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

  • สี่เหลี่ยมผืนผ้าคือวิวพอร์ตละติจูด-ลองจิจูด ซึ่งแสดงเป็น 2 จุด 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 และช่องที่แสดงต้องไม่ว่าง โดยวิวพอร์ตที่ว่างเปล่าจะทำให้เกิดข้อผิดพลาด

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

    "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

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

  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 เพื่อให้การค้นหามุ่งเน้นไปที่สี่เหลี่ยมผืนผ้า วิวพอร์ตได้ด้วย ตัวอย่างต่อไปนี้จำกัดคำขอไว้ที่ย่านใจกลางเมืองซานฟรานซิสโก

  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 ของ "ฟุตบอล" และใช้พารามิเตอร์ 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
      }
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

การปรับตำแหน่ง

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

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

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

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

ลองใช้งาน

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

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

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

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

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