การเติมข้อความอัตโนมัติ (ใหม่) จะแสดงการคาดคะเนสถานที่เพื่อตอบกลับคำขอที่มีสตริงการค้นหาข้อความและขอบเขตทางภูมิศาสตร์ที่ควบคุมพื้นที่ที่ค้นหา การเติมข้อความอัตโนมัติสามารถจับคู่กับคำเต็มและสตริงย่อยของอินพุต การค้นหาชื่อสถานที่ ที่อยู่ และโค้ด 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
มีรายการออบเจ็กต์ AutocompletePrediction
สูงสุด 5 รายการที่แสดงสถานที่ที่คาดการณ์ไว้ รายการอาจว่างเปล่าหากไม่มีตำแหน่งที่ทราบที่ตรงกับการค้นหาและเกณฑ์ตัวกรอง
สำหรับแต่ละสถานที่ที่คาดคะเน คุณสามารถเรียกใช้วิธีต่อไปนี้เพื่อดึงข้อมูลรายละเอียดสถานที่
getFullText(CharacterStyle)
แสดงข้อความทั้งหมดของคำอธิบายสถานที่ ซึ่งจะเป็นการรวมข้อความหลัก และข้อความรอง ตัวอย่างเช่น "Eiffel Tower, Avenue Anatole France, Paris, France" นอกจากนี้ วิธีนี้ยังช่วยให้คุณไฮไลต์ส่วนของคำอธิบายที่ตรงกับการค้นหาด้วยสไตล์ที่คุณต้องการได้โดยใช้CharacterStyle
คุณจะระบุพารามิเตอร์CharacterStyle
หรือไม่ก็ได้ ตั้งค่าเป็นค่าว่างถ้าไม่ต้องการไฮไลต์getPrimaryText(CharacterStyle)
แสดงข้อความหลักที่อธิบายสถานที่ ซึ่งปกติจะเป็นชื่อของสถานที่ ตัวอย่างเช่น "Eiffel Tower" และ "123 Pitt Street"getSecondaryText(CharacterStyle)
แสดงข้อความของบริษัทในเครือของคำอธิบายสถานที่ ซึ่งจะเป็นประโยชน์ เช่น เป็นบรรทัดที่ 2 เมื่อแสดงการคาดคะเนการเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"getPlaceId()
แสดงผลรหัสสถานที่ของสถานที่ที่คาดการณ์ รหัสสถานที่คือตัวระบุแบบข้อความที่ระบุสถานที่ที่ไม่ซ้ำกัน ซึ่งคุณจะใช้เรียกข้อมูลออบเจ็กต์Place
ได้อีกครั้งในภายหลัง สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ในการเติมข้อความอัตโนมัติ โปรดดูรายละเอียดสถานที่ (ใหม่) สำหรับข้อมูลทั่วไปเกี่ยวกับรหัสสถานที่ โปรดดูภาพรวมรหัสสถานที่getTypes()
แสดงรายการประเภทสถานที่ที่เชื่อมโยงกับสถานที่นี้getDistanceMeters()
จะแสดงผลระยะทางเป็นเส้นตรงในหน่วยเมตรระหว่างสถานที่นี้กับต้นทางที่ระบุไว้ในคำขอ
พารามิเตอร์ที่จำเป็น
-
การค้นหา
สตริงข้อความที่จะค้นหา ระบุคำเต็มและสตริงย่อย ชื่อสถานที่ ที่อยู่ และโค้ด Plus บริการเติมข้อความอัตโนมัติ (ใหม่) จะแสดงผลการจับคู่คำที่รอการพิจารณาโดยอิงตามสตริงนี้และผลลัพธ์คำสั่งซื้อตามความเกี่ยวข้องที่รับรู้
หากต้องการตั้งค่าพารามิเตอร์การค้นหา ให้เรียกเมธอด
setQuery()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
พารามิเตอร์ที่ไม่บังคับ
-
ประเภทหลัก
รายการค่าประเภทสูงสุด 5 ประเภทจากประเภทตาราง A หรือตาราง B ที่ใช้กรองสถานที่ที่แสดงในคำตอบ สถานที่ต้องตรงกับค่าประเภทหลักค่าใดค่าหนึ่งที่ระบุไว้จึงจะรวมไว้ในการตอบกลับได้
สถานที่จะมีประเภทหลักได้เพียงประเภทเดียวจากประเภทตาราง ก หรือตาราง ข ที่เชื่อมโยงกับสถานที่นั้น เช่น ประเภทหลักอาจเป็น
"mexican_restaurant"
หรือ"steak_house"
คำขอจะถูกปฏิเสธโดยมีข้อผิดพลาด
INVALID_REQUEST
ในกรณีต่อไปนี้- มีการระบุมากกว่า 5 ประเภท
- ระบบจะระบุประเภทที่ไม่รู้จัก
หากต้องการตั้งค่าพารามิเตอร์ประเภทหลัก ให้เรียกเมธอด
setTypesFilter()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
ประเทศ
รวมเฉพาะผลการค้นหาจากรายชื่อประเทศที่ระบุ ซึ่งระบุเป็นรายการที่มีค่าแบบ 2 อักขระสำหรับ ccTLD ("โดเมนระดับบนสุด") สูงสุด 15 ค่า หากไม่ระบุ จะไม่มีการใช้ข้อจำกัดกับคำตอบ เช่น หากต้องการจำกัดภูมิภาคเป็นเยอรมนีและฝรั่งเศส ให้ทำดังนี้
หากคุณระบุทั้ง
locationRestriction
และincludedRegionCodes
ผลลัพธ์จะอยู่ในบริเวณที่ตัดกันของการตั้งค่าทั้ง 2 รายการหากต้องการตั้งค่าพารามิเตอร์ประเทศ ให้เรียกใช้เมธอด
setCountries()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
ออฟเซ็ตอินพุต
ออฟเซ็ตอักขระ Unicode แบบ 0 ซึ่งระบุตำแหน่งเคอร์เซอร์ในคำค้นหา ตำแหน่งเคอร์เซอร์อาจมีผลต่อการคาดคะเนที่แสดง หากเว้นว่างไว้ ระบบจะใช้ความยาวของคำค้นหาเป็นค่าเริ่มต้น
หากต้องการตั้งค่าพารามิเตอร์ออฟเซ็ตอินพุต ให้เรียกใช้เมธอด
setInputOffset()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
อคติเรื่องตำแหน่งหรือการจำกัดสถานที่
คุณระบุความลำเอียงด้านตำแหน่งหรือข้อจำกัดเกี่ยวกับตำแหน่งได้ แต่ระบุทั้ง 2 อย่างเพื่อระบุพื้นที่ค้นหาได้ ให้คิดว่าการจำกัดตำแหน่งเป็นการระบุภูมิภาคที่ผลการค้นหาจะต้องอยู่ภายใน และการให้น้ำหนักตำแหน่งเป็นการระบุภูมิภาคที่ผลการค้นหาจะต้องอยู่ใกล้เคียง ความแตกต่างหลักคืออาจยังมีการแสดงผลที่อยู่นอกภูมิภาคที่ระบุหากมีการให้น้ำหนักพิเศษกับตำแหน่ง
ความลำเอียงของตำแหน่ง
ระบุพื้นที่ที่จะค้นหา ตำแหน่งนี้ถือว่าเป็นการให้น้ำหนักพิเศษ ไม่ใช่ข้อจำกัด ดังนั้นระบบจึงอาจยังแสดงผลการค้นหานอกพื้นที่ที่ระบุ
หากต้องการตั้งค่าพารามิเตอร์ความเอนเอียงของตำแหน่ง ให้เรียกเมธอด
setLocationBias()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
การจำกัดตำแหน่ง
ระบุพื้นที่ที่จะค้นหา ไม่มีการแสดงผลลัพธ์นอกพื้นที่ที่ระบุ
หากต้องการตั้งค่าพารามิเตอร์การจำกัดตำแหน่ง ให้เรียกเมธอด
setLocationRestriction()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
ระบุการให้น้ำหนักพิเศษเกี่ยวกับสถานที่หรือภูมิภาคการจำกัดสถานที่เป็นวิวพอร์ตสี่เหลี่ยมผืนผ้าหรือเป็นวงกลม
วงกลมกำหนดด้วยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50000.0 ค่าเริ่มต้นคือ 0.0 สำหรับการจำกัดตำแหน่ง คุณต้องกำหนดรัศมีเป็นค่าที่มากกว่า 0.0 ไม่เช่นนั้น คำขอจะไม่แสดงผลลัพธ์
สี่เหลี่ยมผืนผ้าคือวิวพอร์ตละติจูด-ลองจิจูด ซึ่งแสดงในแนวทแยงมุม 2 จุดตรงข้ามกับ
low
และhigh
วิวพอร์ตจะถือเป็นภูมิภาคปิด ซึ่งหมายความว่ามีอาณาเขตรวมอยู่ด้วย ขอบเขตของละติจูดต้องอยู่ระหว่าง -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
โดยช่องที่แสดงจะต้องว่างเปล่า วิวพอร์ตที่ว่างเปล่าจะทำให้เกิดข้อผิดพลาด- หาก
-
Origin
จุดเริ่มต้นที่จะคำนวณระยะทางของเส้นตรงไปยังปลายทาง (เข้าถึงโดยใช้
getDistanceMeters()
) หากไม่ระบุค่านี้ ระบบจะไม่แสดงผลระยะทางของเส้นตรง ต้องระบุเป็นพิกัดละติจูดและลองจิจูด:หากต้องการตั้งค่าพารามิเตอร์ต้นทาง ให้เรียกใช้เมธอด
setOrigin()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
รหัสภูมิภาค
รหัสภูมิภาคที่ใช้ในการจัดรูปแบบการตอบกลับ รวมถึงการจัดรูปแบบที่อยู่ ซึ่งระบุเป็นค่าแบบ 2 อักขระของ ccTLD ("โดเมนระดับบนสุด") รหัส ccTLD ส่วนใหญ่จะเหมือนกับรหัส ISO 3166-1 โดยมีข้อยกเว้นที่สำคัญบางอย่าง เช่น ccTLD ของสหราชอาณาจักรคือ "uk" (.co.uk) ขณะที่รหัส ISO 3166-1 คือ "gb" (ทางเทคนิคสำหรับเอนทิตีของ "สหราชอาณาจักรบริเตนใหญ่และไอร์แลนด์เหนือ")
หากคุณระบุรหัสภูมิภาคไม่ถูกต้อง API จะแสดงข้อผิดพลาด
INVALID_ARGUMENT
พารามิเตอร์อาจส่งผลต่อผลลัพธ์ตามกฎหมายที่เกี่ยวข้องหากต้องการตั้งค่าพารามิเตอร์รหัสภูมิภาค ให้เรียกใช้เมธอด
setRegionCode()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
โทเค็นของเซสชัน
โทเค็นเซสชันเป็นสตริงที่ผู้ใช้สร้างขึ้น ซึ่งจะติดตามการเรียกการเติมข้อความอัตโนมัติ (ใหม่) เป็น "เซสชัน" การเติมข้อความอัตโนมัติใช้โทเค็นเซสชันในการจัดกลุ่มขั้นตอนการค้นหาและการเลือกของการค้นหาในการเติมข้อความอัตโนมัติของผู้ใช้เป็นเซสชันที่แยกกันเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์คำค้นหา และจะสิ้นสุดเมื่อเลือกสถานที่ แต่ละเซสชันมีการค้นหาได้หลายรายการ ตามด้วยการเลือกสถานที่ 1 แห่ง เมื่อเซสชันสิ้นสุดลง โทเค็นจะใช้ไม่ได้อีกต่อไป แอปของคุณต้องสร้างโทเค็นใหม่สําหรับแต่ละเซสชัน เราขอแนะนำให้ใช้โทเค็นเซสชันสำหรับเซสชันการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมทั้งหมด (เมื่อคุณฝังส่วนย่อยหรือเปิดใช้การเติมข้อความอัตโนมัติโดยใช้ Intent แล้ว API จะจัดการกับเรื่องนี้โดยอัตโนมัติ)
การเติมข้อความอัตโนมัติจะใช้
AutocompleteSessionToken
เพื่อระบุแต่ละเซสชัน แอปของคุณควรส่งโทเค็นเซสชันใหม่เมื่อเริ่มต้นเซสชันใหม่แต่ละเซสชัน จากนั้นส่งโทเค็นเดียวกันนั้นพร้อมด้วยรหัสสถานที่ในการเรียกครั้งต่อๆ ไปไปยังfetchPlace()
เพื่อดึงข้อมูลรายละเอียดสถานที่ของสถานที่ที่ผู้ใช้เลือกหากต้องการตั้งค่าพารามิเตอร์โทเค็นเซสชัน ให้เรียกเมธอด
setSessionToken()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
ดูข้อมูลเพิ่มเติมได้ที่โทเค็นเซสชัน
ตัวอย่างการเติมข้อความอัตโนมัติ (ใหม่)
ใช้การจำกัดตำแหน่งและการให้น้ำหนักตำแหน่ง
การเติมข้อความอัตโนมัติ (ใหม่) ใช้การให้น้ำหนัก IP โดยค่าเริ่มต้นเพื่อควบคุมพื้นที่การค้นหา การให้น้ำหนัก IP ทำให้ API ใช้ที่อยู่ IP ของอุปกรณ์เพื่อให้น้ำหนักผลลัพธ์ด้วย คุณเลือกใช้การจำกัดตำแหน่งหรือการให้น้ำหนักพิเศษกับตำแหน่งได้ แต่ใช้ทั้ง 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"
ใช้ต้นทาง
เมื่อคุณใส่พารามิเตอร์ต้นทางในคำขอ โดยระบุเป็นพิกัดละติจูดและลองจิจูด 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