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

เลือกแพลตฟอร์ม แอนดรอยด์ iOS JavaScript บริการผ่านเว็บ

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

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

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

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

การตอบกลับที่เติมข้อความอัตโนมัติ (ใหม่)

API จะแสดงผล FindAutocompletePredictionsResponse ใน Task FindAutocompletePredictionsResponse มีรายการได้สูงสุด 5 รายการ AutocompletePrediction ซึ่งแสดงสถานที่ที่คาดการณ์ไว้ รายการอาจว่างเปล่าหากไม่มีสถานที่ที่รู้จักซึ่งตรงกับคำค้นหาและเกณฑ์ตัวกรอง

คุณสามารถเรียกใช้เมธอดต่อไปนี้เพื่อเรียกรายละเอียดสถานที่ที่คาดการณ์แต่ละแห่งได้

  • getFullText(CharacterStyle) แสดงผลข้อความทั้งหมดของคำอธิบายสถานที่ ข้อความนี้เป็นการผสมผสานระหว่างข้อความหลักและข้อความรอง ตัวอย่างเช่น "หอไอเฟล, Avenue Anatole France, ปารีส, ฝรั่งเศส" นอกจากนี้ วิธีการนี้ช่วยให้คุณไฮไลต์ส่วนของ ที่ตรงกับการค้นหากับรูปแบบที่คุณต้องการ โดยใช้ CharacterStyle คุณจะระบุพารามิเตอร์ CharacterStyle หรือไม่ก็ได้ ตั้งค่าเป็น Null หากไม่ต้องการให้แสดง ไฮไลต์ใดก็ได้
  • getPrimaryText(CharacterStyle) จะแสดงข้อความหลักที่อธิบายสถานที่ ซึ่งโดยปกติจะเป็นชื่อของ เช่น "หอไอเฟล" และ "123 Pitt Street"
  • getSecondaryText(CharacterStyle) แสดงผลข้อความเสริมของคำอธิบายสถานที่ การดำเนินการนี้มีประโยชน์ เช่น ใช้เป็นบรรทัดที่สองเมื่อแสดงการคาดคะเนการเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"
  • getPlaceId() แสดงผลรหัสสถานที่ของสถานที่ที่คาดการณ์ รหัสสถานที่เป็นข้อความ ข้อมูลที่ใช้ในการระบุสถานที่แบบไม่ซ้ำ ซึ่งคุณสามารถใช้เพื่อเรียกดู เวลา Place อีกครั้งในภายหลัง สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน เติมข้อความอัตโนมัติ โปรดดูรายละเอียดสถานที่ (ใหม่) ทั่วไป ข้อมูลเกี่ยวกับรหัสสถานที่ โปรดดูรหัสสถานที่ ภาพรวม
  • getTypes() แสดงรายการประเภทสถานที่ที่เชื่อมโยงกับสถานที่นี้
  • getDistanceMeters() แสดงผลระยะทางตรงเป็นเมตรระหว่างสถานที่นี้กับจุดเริ่มต้นที่ระบุในคำขอ

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

  • การค้นหา

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

    หากต้องการตั้งค่าพารามิเตอร์การค้นหา ให้เรียกใช้เมธอด setQuery() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

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

  • ประเภทหลัก

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

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

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

    • ระบุมากกว่า 5 ประเภท
    • ระบุประเภทที่ไม่รู้จัก

    หากต้องการตั้งค่าพารามิเตอร์ประเภทหลัก ให้เรียกใช้เมธอด setTypesFilter() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

  • ประเทศ

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

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

    หากต้องการตั้งค่าพารามิเตอร์ประเทศ ให้เรียกใช้เมธอด setCountries() เมื่อสร้างออบเจ็กต์ FindAutocompletePredictionsRequest

  • ออฟเซ็ตอินพุต

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

    หากต้องการตั้งค่าพารามิเตอร์ออฟเซ็ตอินพุต ให้เรียกsetInputOffset() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

  • ความลำเอียงด้านสถานที่ตั้งหรือการจำกัดสถานที่ตั้ง

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

    • ความลำเอียงตามสถานที่ตั้ง

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

      หากต้องการตั้งค่าพารามิเตอร์ความเอนเอียงของตำแหน่ง ให้เรียก setLocationBias() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

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

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

      หากต้องการตั้งค่าพารามิเตอร์การจำกัดตำแหน่ง ให้เรียกsetLocationRestriction() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

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

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

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

  • Origin

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

    หากต้องการตั้งค่าพารามิเตอร์ต้นทาง ให้เรียก setOrigin() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

  • รหัสภูมิภาค

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

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

    หากต้องการตั้งค่าพารามิเตอร์รหัสภูมิภาค ให้เรียก setRegionCode() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

  • โทเค็นของเซสชัน

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

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

    หากต้องการตั้งค่าพารามิเตอร์โทเค็นเซสชัน ให้เรียก setSessionToken() เมื่อสร้างวัตถุ FindAutocompletePredictionsRequest

    ดูข้อมูลเพิ่มเติมได้ที่โทเค็นเซสชัน

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

ใช้การจำกัดตำแหน่งและการให้น้ำหนักตำแหน่ง

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

ใช้ประเภทหลัก

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

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

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

ใช้ต้นทาง

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

การระบุแหล่งที่มา

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