ฟีเจอร์เติมข้อความอัตโนมัติ (ใหม่) จะแสดงการคาดคะเนสถานที่เพื่อตอบสนองต่อคําขอที่มีสตริงการค้นหาข้อความและขอบเขตทางภูมิศาสตร์ที่ควบคุมพื้นที่การค้นหา การเติมข้อความอัตโนมัติจะจับคู่กับคำเต็มและสตริงย่อยของอินพุต โดยจะแก้ไขชื่อสถานที่ ที่อยู่ และรหัสบวก แอปพลิเคชันสามารถส่งการค้นหาขณะที่ผู้ใช้พิมพ์ เพื่อแสดงการคาดคะเนสถานที่และการค้นหาขณะนั้น
ตัวอย่างเช่น คุณเรียกใช้ฟีเจอร์เติมข้อความอัตโนมัติโดยใช้สตริงที่มีข้อมูลจากผู้ใช้บางส่วน เช่น "พิซซ่าซิซิลี" โดยจำกัดพื้นที่การค้นหาไว้ที่ซานฟรานซิสโก รัฐแคลิฟอร์เนีย จากนั้นการตอบกลับจะมีรายการสถานที่ที่คาดการณ์ซึ่งตรงกับสตริงการค้นหาและพื้นที่การค้นหา เช่น ร้านอาหารชื่อ "Sicilian Pizza Kitchen"
การคาดคะเนสถานที่ที่แสดงผลออกแบบมาเพื่อแสดงต่อผู้ใช้เพื่อช่วยในการเลือกสถานที่ที่ต้องการ คุณส่งคําขอรายละเอียดสถานที่ (ใหม่) เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับสถานที่ที่คาดการณ์ซึ่งแสดงผลได้
คำขอการเติมข้อความอัตโนมัติ (ใหม่)
แอปของคุณรับรายการชื่อสถานที่และ/หรือที่อยู่ซึ่งคาดคะเนได้จาก Autocomplete 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)
แสดงผลข้อความทั้งหมดของคำอธิบายสถานที่ ข้อความนี้เป็นการผสมผสานระหว่างข้อความหลักและข้อความรอง ตัวอย่างเช่น "หอไอเฟล, 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 Codes บริการการเติมข้อความอัตโนมัติ (ใหม่) จะแสดงรายการที่ตรงกันตามสตริงนี้และจัดเรียงผลลัพธ์ตามความเกี่ยวข้องที่รับรู้
หากต้องการตั้งค่าพารามิเตอร์การค้นหา ให้เรียกใช้เมธอด
setQuery()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
พารามิเตอร์ที่ไม่บังคับ
-
ประเภทหลัก
รายการค่าประเภทสูงสุด 5 รายการจากประเภท Table A หรือ Table B ที่ใช้กรองสถานที่ที่แสดงผลในการตอบกลับ สถานที่ต้องตรงกับค่าประเภทหลักที่ระบุไว้ค่าใดค่าหนึ่งจึงจะรวมอยู่ในคำตอบ
สถานที่หนึ่งๆ อาจมีประเภทหลักได้เพียงประเภทเดียวจากประเภท Table A หรือ Table B ที่เชื่อมโยงอยู่ เช่น ประเภทหลักอาจเป็น
"mexican_restaurant"
หรือ"steak_house"
ระบบจะปฏิเสธคำขอพร้อมข้อผิดพลาด
INVALID_REQUEST
ในกรณีต่อไปนี้- ระบุประเภทมากกว่า 5 ประเภท
- ระบุประเภทที่ไม่รู้จัก
หากต้องการตั้งค่าพารามิเตอร์ประเภทหลัก ให้เรียกใช้เมธอด
setTypesFilter()
เมื่อสร้างออบเจ็กต์FindAutocompletePredictionsRequest
-
ประเทศ
รวมเฉพาะผลลัพธ์จากรายชื่อประเทศที่ระบุ ซึ่งระบุเป็นรายการccTLD ("โดเมนระดับบนสุด") ความยาว 2 อักขระได้สูงสุด 15 รายการ หากไม่ระบุ ระบบจะไม่ใช้ข้อจำกัดกับการตอบกลับ ตัวอย่างเช่น หากต้องการจํากัดภูมิภาคเป็นเยอรมนีและฝรั่งเศส ให้ทําดังนี้
หากคุณระบุทั้ง
locationRestriction
และincludedRegionCodes
ผลลัพธ์จะอยู่ในบริเวณที่ตัดกันของการตั้งค่าทั้ง 2 รายการหากต้องการตั้งค่าพารามิเตอร์ประเทศ ให้เรียกใช้เมธอด
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 แห่ง เมื่อเซสชันสิ้นสุดลง โทเค็นจะใช้งานไม่ได้อีกต่อไป แอปของคุณจึงต้องสร้างโทเค็นใหม่สำหรับแต่ละเซสชัน เราขอแนะนําให้ใช้โทเค็นเซสชันสําหรับเซสชันการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมทั้งหมด (เมื่อคุณฝังข้อมูลโค้ดหรือเปิดการเติมข้อความอัตโนมัติโดยใช้ 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 และการระบุแหล่งที่มา