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

เลือกแพลตฟอร์ม: Android iOS JavaScript บริการเว็บ

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

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

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

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

เช่น คุณเรียก API โดยใช้สตริงที่มีอินพุตบางส่วนของผู้ใช้ "พิซซ่าซิซิลี" เป็นอินพุต โดยจำกัดพื้นที่การค้นหาไว้ที่ซานฟรานซิสโก รัฐแคลิฟอร์เนีย คำตอบจะมีรายการการคาดคะเนสถานที่ที่ตรงกับสตริงการค้นหาและพื้นที่ค้นหา เช่น ร้านอาหารชื่อ "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.place และ suggestions.placePrediction.text ของคําแนะนํา

      X-Goog-FieldMask: places.displayName,places.formattedAddress

    ใช้ * เพื่อเรียกข้อมูลทุกช่อง

      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 ระบบจะแสดงเฉพาะธุรกิจที่มีสถานที่ตั้งจริง

  • includeQueryPredictions

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

  • includedRegionCodes

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

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

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

  • inputOffset

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

  • languageCode

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

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

  • locationBias หรือ locationRestriction

    คุณสามารถระบุ locationBias หรือ locationRestriction เพียงรายการใดรายการหนึ่งเพื่อกําหนดพื้นที่การค้นหา ให้คิดว่า 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 องศา (รวม - 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" (ในทางเทคนิคสำหรับนิติบุคคล "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ")

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

  • sessionToken

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

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

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

locationRestriction ระบุพื้นที่ที่จะค้นหา ไม่มีการแสดงผลลัพธ์นอกพื้นที่ที่ระบุ ในตัวอย่างต่อไปนี้ คุณใช้ locationRestriction เพื่อจำกัดคำขอให้เป็นแวดวง 5,000 เมตรในรัศมี 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"
          ]
        }
      },
    /.../
    ]
  }

ใช้ includePrimaryTypes

ใช้พารามิเตอร์ 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 request เพื่อเพิ่มการคาดคะเนการค้นหาลงในคำตอบ เช่น

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 ไว้ด้วย API จะรวมช่อง 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
      }
    }
  ]
}

ลองใช้งาน

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

  1. เลือกไอคอน API ขยายโปรแกรมสำรวจ API ที่ด้านขวาของหน้า
  2. (ไม่บังคับ) ขยายแสดงพารามิเตอร์มาตรฐาน และตั้งค่าพารามิเตอร์ fields เป็นฟิลด์มาสก์
  3. แก้ไขเนื้อหาคำขอ (ไม่บังคับ)
  4. เลือกปุ่มดำเนินการ ในป๊อปอัป ให้เลือกบัญชีที่ต้องการใช้ส่งคำขอ

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