Place Autocomplete (เดิม)

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

คำขอ Place Autocomplete (เดิม)

Place Autocomplete (เดิม) เป็นส่วนหนึ่งของ Places API และใช้คีย์ API และโควต้าร่วมกับ Places API

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

คุณต้องจัดรูปแบบ Plus Code ให้ถูกต้อง ซึ่งหมายความว่าคุณต้องใช้ URL-escape กับเครื่องหมายบวกเป็น %2B และต้องใช้ URL-escape กับการเว้นวรรคเป็น %20

• รหัสสากล คือรหัสพื้นที่ 4 หลักและรหัสท้องถิ่น 6 หลักขึ้นไป ตัวอย่างเช่น รหัสสากลที่ใช้ Escape ของ URL 849VCWC8+R9 คือ 849VCWC8%2BR9
• รหัสผสมคือรหัสท้องถิ่น 6 หลัก (หรือมากกว่า) ที่มีการระบุตำแหน่งชัดเจน ตัวอย่างเช่น รหัสผสมที่ใช้ Escape ของ URL CWC8+R9 Mountain View, CA, USA คือ CWC8%2BR9%20Mountain%20View%20CA%20USA

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

คำขอ Place Autocomplete (เดิม) คือ HTTP URL ในรูปแบบต่อไปนี้

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

โดยที่ output อาจเป็นค่าใดค่าหนึ่งต่อไปนี้

• json (แนะนำ) บ่งบอกถึงเอาต์พุตใน JavaScript Object Notation (JSON)
• xml ระบุเอาต์พุตเป็น XML

ต้องใช้พารามิเตอร์บางอย่างเพื่อเริ่มคำขอ Place Autocomplete (เดิม) พารามิเตอร์ทั้งหมดจะแยกกันโดยใช้อักขระแอมเพอร์แซนด์ (&) ตามมาตรฐานใน URL รายการพารามิเตอร์และค่าที่เป็นไปได้จะแสดงอยู่ด้านล่าง

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

อินพุต

สตริงข้อความที่จะค้นหา บริการ Place Autocomplete จะแสดงผลลัพธ์ที่ตรงกันซึ่งเป็นไปได้โดยอิงตามสตริงนี้ และจัดเรียงผลลัพธ์ตามความเกี่ยวข้องที่รับรู้

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

คอมโพเนนต์

การจัดกลุ่มสถานที่ที่คุณต้องการจำกัดผลการค้นหา คุณใช้คอมโพเนนต์เพื่อกรองตามประเทศได้สูงสุด 5 ประเทศ ต้องส่งประเทศเป็นรหัสประเทศที่เข้ากันได้กับ ISO 3166-1 Alpha-2 แบบ 2 อักขระ เช่น components=country:fr จะจำกัดผลการค้นหาเฉพาะสถานที่ในฝรั่งเศส ต้องส่งหลายประเทศเป็นตัวกรอง country:XX หลายรายการ โดยใช้อักขระไปป์ | เป็นตัวคั่น ตัวอย่างเช่น components=country:us|country:pr|country:vi|country:gu|country:mp จะจำกัดผลการค้นหาให้อยู่ภายในสหรัฐอเมริกาและเขตแดนที่ไม่ได้รวมเป็นรัฐ

ภาษา

ภาษาที่จะแสดงผลลัพธ์

• ดูรายการภาษาที่รองรับ Google อัปเดตภาษาที่รองรับอยู่บ่อยครั้ง รายการนี้จึงอาจไม่ครอบคลุมทั้งหมด
• หากไม่ได้ระบุ language ไว้ API จะพยายามใช้ภาษาที่ต้องการตามที่ระบุไว้ในส่วนหัว Accept-Language
• API จะพยายามอย่างเต็มที่เพื่อให้ที่อยู่ที่อ่านง่ายสำหรับทั้งผู้ใช้และคนในพื้นที่ เพื่อให้บรรลุเป้าหมายดังกล่าว ระบบจะแสดงที่อยู่ในภาษาท้องถิ่น โดยแปลงเป็นสคริปต์ที่ผู้ใช้อ่านได้หากจำเป็น ตามภาษาที่ต้องการ ส่วนที่อยู่อื่นๆ จะแสดงในภาษาที่ต้องการ คอมโพเนนต์ของที่อยู่ ทั้งหมดจะแสดงในภาษาเดียวกัน ซึ่งเลือกจากคอมโพเนนต์แรก
• หากชื่อไม่มีในภาษาที่ต้องการ API จะใช้ชื่อที่ใกล้เคียงที่สุด
• ภาษาที่ต้องการมีอิทธิพลเล็กน้อยต่อชุดผลลัพธ์ที่ API เลือกแสดงผลและลำดับการแสดงผล โปรแกรมเข้ารหัสพิกัดภูมิศาสตร์จะตีความตัวย่อแตกต่างกันไปตามภาษา เช่น ตัวย่อของประเภทถนน หรือคำพ้องความหมายที่อาจใช้ได้ในภาษาหนึ่งแต่ใช้ไม่ได้ในอีกภาษาหนึ่ง เช่น utca และ tér เป็นคำพ้องความหมายของคำว่าถนนในภาษาฮังการี

สถานที่

จุดที่ต้องการดึงข้อมูลสถานที่ ต้องระบุเป็น latitude,longitude นอกจากนี้ คุณต้องระบุพารามิเตอร์ radius เมื่อระบุสถานที่ตั้งด้วย หากไม่ได้ระบุ radius ระบบจะไม่สนใจพารามิเตอร์ location

locationbias

แสดงผลการค้นหาในพื้นที่ที่ระบุ โดยระบุรัศมีบวกละติจูด/ลองจิจูด หรือคู่ละติจูด/ลองจิจูด 2 คู่ที่แสดงจุดของสี่เหลี่ยมผืนผ้า หากไม่ได้ระบุพารามิเตอร์นี้ API จะใช้การให้น้ำหนักที่อยู่ IP โดยค่าเริ่มต้น

• การให้น้ำหนัก IP: สั่งให้ API ใช้การให้น้ำหนักที่อยู่ IP ส่งสตริง ipbias (ตัวเลือกนี้ไม่มีพารามิเตอร์เพิ่มเติม)
• วงกลม: สตริงที่ระบุรัศมีเป็นเมตร บวกกับละติจูด/ลองจิจูดเป็นองศาทศนิยม โดยใช้รูปแบบต่อไปนี้ circle:radius@lat,lng
• สี่เหลี่ยมผืนผ้า: สตริงที่ระบุคู่ละติจูด/ลองจิจูด 2 คู่ในหน่วยองศาทศนิยม ซึ่งแสดงจุดใต้/ตะวันตกและเหนือ/ตะวันออกของสี่เหลี่ยมผืนผ้า โดยใช้รูปแบบต่อไปนี้rectangle:south,west|north,east โปรดทราบว่าค่าตะวันออก/ตะวันตกจะรวมอยู่ในช่วง -180, 180 และค่าเหนือ/ใต้จะถูกจำกัดให้อยู่ในช่วง -90, 90

locationrestriction

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

• วงกลม: สตริงที่ระบุรัศมีเป็นเมตร บวกกับละติจูด/ลองจิจูดเป็นองศาทศนิยม โดยใช้รูปแบบต่อไปนี้ circle:radius@lat,lng
• สี่เหลี่ยมผืนผ้า: สตริงที่ระบุคู่ละติจูด/ลองจิจูด 2 คู่ในหน่วยองศาทศนิยม ซึ่งแสดงจุดใต้/ตะวันตกและเหนือ/ตะวันออกของสี่เหลี่ยมผืนผ้า โดยใช้รูปแบบต่อไปนี้rectangle:south,west|north,east โปรดทราบว่าค่าตะวันออก/ตะวันตกจะรวมอยู่ในช่วง -180, 180 และค่าเหนือ/ใต้จะถูกจำกัดให้อยู่ในช่วง -90, 90

offset

ตำแหน่งในคำที่ป้อนของอักขระสุดท้ายที่บริการใช้เพื่อจับคู่การคาดคะเน เช่น หากอินพุตคือ Google และออฟเซ็ตคือ 3 บริการจะจับคู่กับ Goo สตริงที่กำหนดโดยออฟเซ็ตจะจับคู่กับคำแรกในคำที่ป้อนเท่านั้น เช่น หากคำที่ป้อนคือ Google abc และออฟเซ็ตคือ 3 บริการจะพยายามจับคู่กับ Goo abc หากไม่ได้ระบุออฟเซ็ต บริการจะใช้ทั้งคำ โดยทั่วไปแล้ว ควรกำหนดออฟเซ็ตเป็นตำแหน่งของเคอร์เซอร์ข้อความ

origin

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

รัศมี

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

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

• เติมข้อความอัตโนมัติ: 50,000 เมตร
• การค้นหาในบริเวณใกล้เคียง:
  • เมื่อใช้ keyword หรือ name: 50,000 เมตร
  • โดยไม่ต้องใช้ keyword หรือ name
    • สูงสุด 50,000 เมตร โดยปรับแบบไดนามิกตามความหนาแน่นของพื้นที่ โดยไม่ขึ้นอยู่กับพารามิเตอร์ rankby
    • เมื่อใช้ rankby=distance ระบบจะไม่ยอมรับพารามิเตอร์รัศมี และจะส่งผลให้เกิด INVALID_REQUEST
• การเติมข้อความค้นหาอัตโนมัติ: 50,000 เมตร
• การค้นหาข้อความ: 50,000 เมตร

ภูมิภาค

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

sessiontoken

สตริงแบบสุ่มที่ระบุเซสชันการเติมข้อความอัตโนมัติเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน

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

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

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

strictbounds

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

ประเภท

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

สถานที่หนึ่งๆ จะมีประเภทหลักได้เพียงประเภทเดียวจากประเภทที่แสดงในตารางที่ 1 หรือตารางที่ 2 เช่น โรงแรมที่เสิร์ฟอาหารอาจแสดงผลเฉพาะเมื่อค้นหาด้วย types=lodging แต่ไม่แสดงเมื่อค้นหาด้วย types=restaurant

คุณสามารถระบุค่าของพารามิเตอร์ types ได้ดังนี้

• ค่าสูงสุด 5 ค่าจากตารางที่ 1 หรือตารางที่ 2 หากมีหลายค่า ให้คั่นแต่ละค่าด้วย | (แถบแนวตั้ง) เช่น

  types=book_store|cafe

• ตัวกรองที่รองรับรายการใดรายการหนึ่งในตารางที่ 3 คุณไม่สามารถผสมคอลเล็กชันประเภทต่างๆ ได้

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

• มีการระบุมากกว่า 5 ประเภท
• มีประเภทที่ไม่รู้จักปรากฏอยู่
• ประเภทใดก็ตามจากตารางที่ 1 หรือตารางที่ 2 จะผสมกับตัวกรองใดก็ได้ในตารางที่ 3

ตัวอย่าง Place Autocomplete (เดิม)

คำขอสำหรับสถานประกอบการที่มีสตริง "Amoeba" ภายในพื้นที่ที่มีศูนย์กลางอยู่ที่ซานฟรานซิสโก แคลิฟอร์เนีย

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

คำขอเดียวกันซึ่งจำกัดผลการค้นหาให้อยู่ภายในระยะ 500 เมตรจาก Ashbury St & Haight St, San Francisco

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

คำขอที่อยู่ที่มีคำว่า "Vict" พร้อมผลลัพธ์เป็นภาษาฝรั่งเศส

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

คำขอเมืองที่มีคำว่า "Vict" พร้อมผลลัพธ์เป็นภาษาโปรตุเกสแบบบราซิล

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

โปรดทราบว่าคุณจะต้องแทนที่คีย์ API ในตัวอย่างเหล่านี้ด้วยคีย์ของคุณเอง

การตอบกลับของ Place Autocomplete (เดิม)

ระบบจะแสดงผลการตอบกลับของ Place Autocomplete (เดิม) ในรูปแบบที่ระบุโดยแฟล็ก output ภายในเส้นทาง URL ของคำขอ ผลลัพธ์ด้านล่างเป็นตัวอย่างของสิ่งที่อาจแสดงผลสำหรับการค้นหาที่มีพารามิเตอร์ต่อไปนี้

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

   

PlacesAutocompleteResponse

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

การตอบกลับ XML ประกอบด้วยองค์ประกอบ <AutocompletionResponse> รายการเดียวที่มีองค์ประกอบย่อย 2 ประเภท ได้แก่

• องค์ประกอบ <status> รายการเดียวจะมีข้อมูลเมตาเกี่ยวกับคำขอ ดูรหัสสถานะด้านล่าง
• องค์ประกอบ <prediction> อย่างน้อย 0 รายการ โดยแต่ละรายการมีข้อมูลเกี่ยวกับสถานที่เดียว ดูข้อมูลเกี่ยวกับผลลัพธ์เหล่านี้ได้ที่ผลลัพธ์ของ Place Autocomplete (เดิม) Places API จะแสดงผลลัพธ์สูงสุด 5 รายการ

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

PlacesAutocompleteStatus

รหัสสถานะที่บริการแสดงผล

• OK ซึ่งบ่งบอกว่าคำขอ API สำเร็จแล้ว
• ZERO_RESULTS ซึ่งบ่งบอกว่าการค้นหาสำเร็จแต่ไม่พบผลลัพธ์ กรณีนี้อาจเกิดขึ้นหากการค้นหาผ่านขอบเขตในสถานที่ห่างไกล
• INVALID_REQUEST ซึ่งบ่งชี้ว่าคำขอ API มีรูปแบบไม่ถูกต้อง โดยทั่วไปเกิดจากไม่มีพารามิเตอร์ input
• OVER_QUERY_LIMIT ที่ระบุถึงสิ่งต่อไปนี้
  • คุณใช้ QPS เกินขีดจำกัดแล้ว
  • ยังไม่ได้เปิดใช้การเรียกเก็บเงินในบัญชีของคุณ
  • เครดิตรายเดือน $200 หรือขีดจำกัดการใช้งานที่กำหนดเองเกินขีดจำกัดแล้ว
  • วิธีการชำระเงินที่ระบุใช้ไม่ได้อีกต่อไป (เช่น บัตรเครดิตหมดอายุ)
  ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีแก้ไขข้อผิดพลาดนี้ได้ที่คำถามที่พบบ่อยเกี่ยวกับ Maps
• REQUEST_DENIED ซึ่งระบุว่าคำขอของคุณถูกปฏิเสธ โดยทั่วไปแล้วเป็นเพราะสาเหตุต่อไปนี้
  • คำขอไม่มีคีย์ API
  • พารามิเตอร์ key ไม่ถูกต้อง
• UNKNOWN_ERROR ซึ่งบ่งบอกถึงข้อผิดพลาดที่ไม่รู้จัก

เมื่อบริการ Places แสดงผลลัพธ์ JSON จากการค้นหา ระบบจะวางผลลัพธ์เหล่านั้นไว้ในอาร์เรย์ predictions แม้ว่าบริการจะไม่แสดงผลลัพธ์ (เช่น หาก location อยู่ระยะไกล) บริการจะยังคงแสดงอาร์เรย์ predictions ที่ว่างเปล่า การตอบกลับ XML ประกอบด้วยองค์ประกอบ <prediction> ตั้งแต่ 0 รายการขึ้นไป

PlaceAutocompletePrediction

PlaceAutocompleteMatchedSubstring

PlaceAutocompleteStructuredFormat

PlaceAutocompleteTerm

การเพิ่มประสิทธิภาพ Place Autocomplete (เดิม)

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

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

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

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

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

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

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

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

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

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

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

Place Autocomplete ตามเซสชัน (เดิม) พร้อมรายละเอียดสถานที่ (เดิม)

ใช้ Place Autocomplete ตามเซสชัน (เดิม) กับรายละเอียดสถานที่ (เดิม)
เนื่องจากแอปพลิเคชันของคุณต้องใช้รายละเอียดสถานที่ (เดิม) เช่น ชื่อสถานที่ สถานะธุรกิจ หรือเวลาทำการ การติดตั้งใช้งาน Place Autocomplete (เดิม) จึงควรใช้โทเค็นของเซสชัน (แบบเป็นโปรแกรมหรือฝังในวิดเจ็ต JavaScript, Android หรือ iOS) ต่อเซสชัน รวมถึง SKU ข้อมูล Places ที่เกี่ยวข้อง โดยขึ้นอยู่กับฟิลด์ข้อมูลสถานที่ที่คุณขอ¹

การติดตั้งใช้งานวิดเจ็ต
การจัดการเซสชันจะติดตั้งมาในวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งรวมถึงทั้งคำขอ Place Autocomplete (เดิม) และคำขอรายละเอียดสถานที่ (เดิม) ในการคาดคะเนที่เลือก อย่าลืมระบุพารามิเตอร์ fields เพื่อให้มั่นใจว่าคุณขอเฉพาะฟิลด์ข้อมูล Place Autocomplete (เดิม) ที่ต้องการเท่านั้น

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

1. รหัสสถานที่จากการตอบกลับของ Place Autocomplete (เดิม)
2. โทเค็นของเซสชันที่ใช้ในคำขอ Place Autocomplete (เดิม)
3. พารามิเตอร์ fields ที่ระบุ ฟิลด์ข้อมูล Place Autocomplete (เดิม) ที่คุณต้องการ

Place Autocomplete (เดิม) ต่อคำขอที่มี Geocoding API

ใช้ Place Autocomplete (เดิม) แบบเป็นโปรแกรมโดยไม่มีโทเค็นของเซสชัน และเรียกใช้ Geocoding API ในการคาดคะเนสถานที่ที่เลือก
Geocoding API จะแสดงที่อยู่และพิกัดละติจูด/ลองจิจูด การส่งคำขอ Autocomplete - ต่อคำขอ 4 รายการบวกกับการเรียกใช้ Geocoding API เกี่ยวกับการคาดคะเนสถานที่ที่เลือกจะมีค่าใช้จ่ายน้อยกว่า Place Autocomplete (เดิม) ต่อเซสชัน¹

ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดคะเนที่ต้องการโดยใช้อักขระน้อยลง

Place Autocomplete ตามเซสชัน (เดิม) สำหรับแอปพลิเคชันที่ใช้ที่อยู่เท่านั้น

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

การติดตั้งใช้งานวิดเจ็ต
การจัดการเซสชันจะติดตั้งมาในวิดเจ็ต JavaScript, Android หรือ iOS โดยอัตโนมัติ ซึ่งรวมถึงทั้งคำขอ Place Autocomplete (เดิม) และคำขอรายละเอียดสถานที่ (เดิม) ในการคาดคะเนที่เลือก อย่าลืมระบุพารามิเตอร์ fields เพื่อให้แน่ใจว่าคุณขอเฉพาะช่องที่ต้องการเท่านั้น

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

1. รหัสสถานที่จากการตอบกลับของ Place Autocomplete (เดิม)
2. โทเค็นของเซสชันที่ใช้ในคำขอ Place Autocomplete (เดิม)
3. พารามิเตอร์ fields ที่ระบุฟิลด์ข้อมูลพื้นฐาน เช่น ที่อยู่และเรขาคณิต

พิจารณาเลื่อนคำขอ Place Autocomplete (เดิม)
คุณสามารถใช้กลยุทธ์ต่างๆ เช่น เลื่อนคำขอ Place Autocomplete (เดิม) ออกไปจนกว่าผู้ใช้จะพิมพ์อักขระ 3 หรือ 4 ตัวแรก เพื่อให้แอปพลิเคชันส่งคำขอน้อยลง ตัวอย่างเช่น การส่งคำขอ Place Autocomplete (เดิม) สำหรับอักขระแต่ละตัวหลังจากที่ผู้ใช้พิมพ์อักขระตัวที่ 3 หมายความว่าหากผู้ใช้พิมพ์อักขระ 7 ตัวแล้วเลือกการคาดคะเนที่คุณส่งคำขอ Geocoding API 1 รายการ ค่าใช้จ่ายทั้งหมดจะเป็นค่าใช้จ่ายสำหรับ Place Autocomplete (เดิม) 4 รายการต่อคำขอ + การเข้ารหัสพิกัดภูมิศาสตร์¹

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

ลองใช้แนวทางปฏิบัติแนะนำด้านประสิทธิภาพเพื่อช่วยให้ผู้ใช้ได้รับการคาดคะเนที่ต้องการโดยใช้อักขระน้อยลง

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

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

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

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

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

การจำกัดสถานที่ตั้ง

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

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