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

เลือกแพลตฟอร์ม: Android iOS JavaScript Web Service
นักพัฒนาแอปในเขตเศรษฐกิจยุโรป (EEA)

บทนำ

การเติมข้อความอัตโนมัติ (ใหม่) เป็นบริการเว็บที่แสดงการคาดคะเนสถานที่ และการคาดคะเนคำค้นหาเพื่อตอบสนองต่อคำขอ 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

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

พารามิเตอร์

คำอธิบาย

input*

สตริงข้อความที่จะค้นหา (คำเต็ม สตริงย่อย ชื่อสถานที่ ที่อยู่ โค้ด Plus)

FieldMask (ส่วนหัว HTTP)

รายการที่คั่นด้วยคอมมาซึ่งระบุช่องที่จะแสดงผลใน การตอบกลับ

includedPrimaryTypes

จำกัดผลการค้นหาให้แสดงเฉพาะสถานที่ที่ตรงกับประเภทหลักที่ระบุสูงสุด 5 ประเภท

includePureServiceAreaBusinesses

หากเป็นจริง จะรวมธุรกิจที่ไม่มีสถานที่ตั้งจริง (ธุรกิจที่ให้บริการตามสถานที่) ค่าเริ่มต้นคือ false

includeQueryPredictions

หากเป็นจริง จะรวมทั้งการคาดคะเนสถานที่และการคาดคะเนการค้นหาไว้ใน การตอบกลับ ค่าเริ่มต้นคือ false

includedRegionCodes

อาร์เรย์ของรหัสประเทศ 2 ตัวอักษรสูงสุด 15 รายการเพื่อจำกัด ผลลัพธ์

inputOffset

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

languageCode

ภาษาที่ต้องการ (รหัส IETF BCP-47) สำหรับผลลัพธ์ ค่าเริ่มต้นคือส่วนหัว Accept-Language หรือ "en"

locationBias

ระบุพื้นที่ (วงกลมหรือสี่เหลี่ยมผืนผ้า) เพื่อให้ผลการค้นหามีแนวโน้มไปในทิศทางนั้น โดยอนุญาตให้แสดงผลการค้นหาที่อยู่นอกพื้นที่ได้ ใช้กับ locationRestriction ไม่ได้

locationRestriction

ระบุพื้นที่ (วงกลมหรือสี่เหลี่ยมผืนผ้า) เพื่อจำกัดผลการค้นหา ภายใน ระบบจะไม่แสดงผลลัพธ์ที่อยู่นอกพื้นที่นี้ ใช้กับ locationBias ไม่ได้

origin

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

regionCode

รหัสภูมิภาคที่ใช้ในการจัดรูปแบบการตอบกลับและคำแนะนำ (เช่น 'uk', 'fr')

sessionToken

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

เกี่ยวกับการตอบกลับ

ฟีเจอร์เติมข้อความอัตโนมัติ (ใหม่) จะแสดงผลออบเจ็กต์ 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 หรือหากสถานที่ที่แสดงไม่มีการแปลจาก ภาษาท้องถิ่นเป็น inputlanguageCode

    • คุณต้องใช้รหัสภาษา 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

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

เลือกพารามิเตอร์เพื่อเอนเอียงผลลัพธ์

พารามิเตอร์การเติมข้อความอัตโนมัติ (ใหม่) อาจส่งผลต่อผลการค้นหาแตกต่างกัน ตารางต่อไปนี้แสดงคําแนะนําสําหรับการใช้พารามิเตอร์ตามผลลัพธ์ที่ต้องการ
พารามิเตอร์ คำแนะนำในการใช้งาน
regionCode ตั้งค่าตามค่ากำหนดระดับภูมิภาคของผู้ใช้
includedRegionCodes ตั้งค่าเพื่อจำกัดผลลัพธ์ให้แสดงเฉพาะภูมิภาคที่ระบุ
locationBias ใช้เมื่อต้องการผลลัพธ์ในหรือรอบๆ ภูมิภาค หากเกี่ยวข้อง กำหนดภูมิภาคเป็นวิวพอร์ตของแผนที่ที่ผู้ใช้กำลังดู
locationRestriction ใช้ only เมื่อไม่ควรแสดงผลลัพธ์นอกภูมิภาค
origin ใช้เมื่อต้องการระยะทางเส้นตรงไปยัง การคาดการณ์แต่ละรายการ

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

จำกัดการค้นหาในพื้นที่โดยใช้ 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 ต่อผู้ใช้เพื่อหลีกเลี่ยงการทำให้ผู้ใช้เข้าใจผิด

ลองใช้งาน

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

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

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

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

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