การเติมข้อความอัตโนมัติ (ใหม่) จะแสดงผลการคาดคะเนสถานที่เพื่อตอบสนองต่อคำขอที่มีสตริงค้นหาข้อความและขอบเขตทางภูมิศาสตร์ที่ควบคุมพื้นที่การค้นหา การเติมข้อความอัตโนมัติสามารถจับคู่กับคำเต็มและสตริงย่อยของอินพุต ซึ่งจะช่วยหาชื่อสถานที่ ที่อยู่ และรหัสบวก แอปพลิเคชันของคุณสามารถส่งข้อความค้นหาตามที่ผู้ใช้พิมพ์ เพื่อคาดการณ์สถานที่และการคาดคะเนการค้นหาในทันที
ตัวอย่างเช่น คุณอาจเรียกการเติมข้อความอัตโนมัติโดยใช้สตริงที่มีอินพุตของผู้ใช้บางส่วนว่า "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
หรือไม่ก็ได้ ตั้งค่าเป็น Null หากคุณไม่จำเป็นต้องใช้ไฮไลต์getPrimaryText(CharacterStyle)
แสดงข้อความหลักที่อธิบายสถานที่ ซึ่งโดยปกติจะเป็นชื่อของสถานที่นั้น เช่น "หอไอเฟล" และ "123 ถนนพิตต์"getSecondaryText(CharacterStyle)
แสดงข้อความบริษัทในเครือของคำอธิบายสถานที่ ซึ่งจะเป็นประโยชน์ เช่น แสดงเป็นบรรทัดที่ 2 เมื่อแสดงการคาดคะเนเพื่อเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"getPlaceId()
จะแสดงรหัสของสถานที่ที่คาดไว้ รหัสสถานที่คือตัวระบุแบบข้อความที่ระบุสถานที่โดยไม่ซ้ำกัน ซึ่งคุณสามารถใช้เพื่อเรียกออบเจ็กต์Place
อีกครั้งในภายหลังได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน การเติมข้อความอัตโนมัติได้ที่รายละเอียดสถานที่ (ใหม่) ดูข้อมูลทั่วไปเกี่ยวกับรหัสสถานที่ได้ที่ภาพรวมรหัสสถานที่getTypes()
จะแสดงรายการประเภทสถานที่ที่เกี่ยวข้องกับสถานที่นี้getDistanceMeters()
แสดงระยะทางของเส้นตรงในหน่วยเมตรระหว่างสถานที่นี้กับต้นทางที่ระบุไว้ในคำขอ
พารามิเตอร์ที่จำเป็น
-
การค้นหา
สตริงข้อความที่จะค้นหา ระบุคำเต็มและสตริงย่อย ชื่อสถานที่ ที่อยู่ และโค้ด Plus บริการเติมข้อความอัตโนมัติ (ใหม่) จะแสดงตัวเลือกที่ตรงกันตามสตริงนี้และผลลัพธ์คำสั่งซื้อตามความเกี่ยวข้องที่รับรู้ได้
หากต้องการตั้งค่าพารามิเตอร์การค้นหา ให้เรียกใช้เมธอด
setQuery()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
พารามิเตอร์ที่ไม่บังคับ
-
ประเภทหลัก
รายการค่าประเภทสูงสุด 5 ประเภทจากประเภทตาราง ก หรือตาราง ข ที่ใช้กรองสถานที่ที่แสดงในคำตอบ สถานที่ต้องตรงกับค่าประเภทหลักที่ระบุไว้จึงจะรวมไว้ในคำตอบได้
สถานที่จะมีประเภทหลักได้เพียงประเภทเดียวจากตาราง ก หรือตาราง ข ที่เชื่อมโยงกับสถานที่ดังกล่าว ตัวอย่างเช่น ประเภทหลักอาจเป็น
"mexican_restaurant"
หรือ"steak_house"
คำขอถูกปฏิเสธโดยมีข้อผิดพลาด
INVALID_REQUEST
ในกรณีต่อไปนี้- มีการระบุมากกว่าห้าประเภท
- มีการระบุประเภทที่ไม่รู้จัก
หากต้องการตั้งค่าพารามิเตอร์ประเภทหลัก ให้เรียกใช้เมธอด
setTypesFilter()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
ประเทศ
ใส่เฉพาะผลการค้นหาจากรายการประเทศที่ระบุ โดยระบุเป็นรายการค่า 2 อักขระของ ccTLD ("โดเมนระดับบนสุด") ไม่เกิน 15 รายการ หากไม่ระบุ ระบบจะไม่ใช้ข้อจำกัดกับคำตอบ เช่น หากต้องการจำกัดภูมิภาคให้มีเฉพาะเยอรมนีและฝรั่งเศส ให้ทำดังนี้
หากคุณระบุทั้ง
locationRestriction
และincludedRegionCodes
ผลลัพธ์จะอยู่ในบริเวณจุดตัดของการตั้งค่า 2 รายการหากต้องการตั้งค่าพารามิเตอร์ประเทศ ให้เรียกใช้เมธอด
setCountries()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
ออฟเซ็ตของอินพุต
ออฟเซ็ตอักขระ Unicode แบบเลข 0 ที่ระบุตำแหน่งเคอร์เซอร์ในการค้นหา ตำแหน่งเคอร์เซอร์อาจส่งผลต่อการคาดคะเนที่จะแสดงผล หากเว้นว่างไว้ ระบบจะใช้ความยาวของคำค้นหาเป็นค่าเริ่มต้น
หากต้องการตั้งค่าพารามิเตอร์ออฟเซ็ตอินพุต ให้เรียกใช้เมธอด
setInputOffset()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
การให้น้ำหนักพิเศษกับตำแหน่งหรือการจำกัดตำแหน่ง
คุณจะระบุการให้น้ำหนักพิเศษเกี่ยวกับตำแหน่งหรือการจำกัดตำแหน่งได้ แต่ไม่ใช่ทั้ง 2 อย่าง เพื่อกำหนดพื้นที่การค้นหา ให้คิดว่าการจำกัดตำแหน่งเป็นการระบุภูมิภาคที่ผลลัพธ์ต้องอยู่ภายใน และการให้น้ำหนักตำแหน่งเป็นการระบุภูมิภาคที่ผลลัพธ์ต้องอยู่ใกล้ ความแตกต่างที่สำคัญคือ เมื่อมีการให้น้ำหนักตำแหน่ง ระบบอาจยังคงแสดงผลลัพธ์ที่อยู่นอกภูมิภาคที่ระบุ
การให้น้ำหนักพิเศษกับสถานที่ตั้ง
ระบุพื้นที่ที่จะค้นหา ตำแหน่งนี้ถือเป็นการให้น้ำหนักพิเศษ ไม่ใช่ข้อจำกัด ดังนั้นระบบจึงอาจยังแสดงผลลัพธ์ที่อยู่นอกพื้นที่ที่ระบุ
หากต้องการตั้งค่าพารามิเตอร์การให้น้ำหนักพิเศษตำแหน่ง ให้เรียกใช้เมธอด
setLocationBias()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
การจำกัดสถานที่
ระบุพื้นที่ที่จะค้นหา ระบบจะไม่แสดงผลลัพธ์นอกพื้นที่ที่ระบุ
หากต้องการตั้งค่าพารามิเตอร์การจำกัดตำแหน่ง ให้เรียกใช้เมธอด
setLocationRestriction()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
ระบุการให้น้ำหนักพิเศษตามตำแหน่งหรือเขตการจำกัดตำแหน่งเป็นวิวพอร์ตแบบสี่เหลี่ยมผืนผ้าหรือเป็นวงกลม
วงกลมจะกำหนดโดยจุดศูนย์กลางและรัศมีเป็นเมตร รัศมีต้องอยู่ระหว่าง 0.0 ถึง 50, 000.0 ค่าเริ่มต้นคือ 0.0 สำหรับการจำกัดสถานที่ คุณต้องตั้งค่ารัศมีเป็นค่าที่มากกว่า 0.0 มิเช่นนั้น คำขอจะไม่แสดงผลลัพธ์
สี่เหลี่ยมผืนผ้าคือวิวพอร์ตละติจูด-ลองจิจูด ซึ่งแสดงเป็นแนวทแยงมุม 2 จุดตรงข้าม
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
-
รหัสภูมิภาค
รหัสภูมิภาคที่ใช้ในการจัดรูปแบบการตอบกลับ รวมถึงการจัดรูปแบบที่อยู่ ซึ่งระบุเป็นค่าอักขระ 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"
ใช้ต้นทาง
เมื่อคุณใส่พารามิเตอร์ 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 เมื่อคุณแสดงการคาดคะเนจากบริการเติมข้อความอัตโนมัติ (ใหม่) โดยไม่มีแผนที่ คุณต้องรวมโลโก้ Google ที่แสดงในบรรทัดกับช่องค้นหา/ผลลัพธ์ สำหรับข้อมูลเพิ่มเติม โปรดดูการแสดงโลโก้ Google และการระบุแหล่งที่มา