Place Autocomplete

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

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

คุณเพิ่มการเติมข้อความอัตโนมัติลงในแอปได้ด้วยวิธีต่อไปนี้

เพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติ

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

คุณมี 2 ตัวเลือกในการเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติลงในแอป ดังนี้

ตัวเลือกที่ 1: ฝัง AutocompleteSupportFragment

หากต้องการเพิ่ม AutocompleteSupportFragment ลงในแอป ให้ทำตามขั้นตอนต่อไปนี้

  1. เพิ่ม Fragment ลงในเลย์เอาต์ XML ของกิจกรรม
  2. เพิ่ม Listener ลงในกิจกรรมหรือ Fragment

เพิ่ม AutocompleteSupportFragment ลงในกิจกรรม

หากต้องการเพิ่ม AutocompleteSupportFragment ลงในกิจกรรม ให้เพิ่ม Fragment ใหม่ลงในเลย์เอาต์ XML เช่น

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • โดยค่าเริ่มต้น ข้อความที่ไฮไลต์จะไม่มีเส้นขอบหรือพื้นหลัง หากต้องการให้มีลักษณะที่มองเห็นสอดคล้องกัน ให้ซ้อน Fragment ภายในองค์ประกอบเลย์เอาต์อื่น เช่น CardView
  • หากคุณใช้ส่วนเติมข้อความอัตโนมัติและต้องการลบล้าง onActivityResult คุณต้องเรียกใช้ super.onActivityResult ไม่เช่นนั้นส่วนเติมข้อความจะไม่ทำงานอย่างถูกต้อง

เพิ่ม PlaceSelectionListener ลงในกิจกรรม

PlaceSelectionListener จัดการการแสดงสถานที่เพื่อตอบสนองต่อการเลือกของผู้ใช้ โค้ดต่อไปนี้แสดงการสร้างการอ้างอิงไปยัง Fragment และ การเพิ่ม Listener ลงใน AutocompleteSupportFragment

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            Log.i(TAG, "An error occurred: $status")
        }
    })

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

ตัวเลือกที่ 2: ใช้ Intent เพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ

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

หากต้องการเปิดวิดเจ็ตการเติมข้อความอัตโนมัติโดยใช้ Intent ให้ทำตามขั้นตอนต่อไปนี้

  1. ใช้ Autocomplete.IntentBuilder เพื่อสร้าง Intent โดยส่งโหมด Autocomplete ที่ต้องการ
  2. กำหนดตัวเรียกใช้ผลลัพธ์ของกิจกรรม registerForActivityResult ที่ใช้เพื่อเปิด Intent และจัดการการคาดคะเนสถานที่ที่ผู้ใช้เลือก ในผลลัพธ์ได้

สร้างความตั้งใจในการเติมข้อความอัตโนมัติ

ตัวอย่างด้านล่างใช้ Autocomplete.IntentBuilder เพื่อสร้าง Intent สำหรับเปิดวิดเจ็ตการเติมข้อความอัตโนมัติเป็น Intent

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .build(this)

    startAutocomplete.launch(intent)

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);
    startAutocomplete.launch(intent);

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

เมื่อแสดงในโหมดซ้อนทับ วิดเจ็ตเติมข้อความอัตโนมัติจะปรากฏซ้อนทับ UI การโทร
รูปที่ 1: วิดเจ็ตการเติมข้อความอัตโนมัติในโหมดซ้อนทับ
เมื่อแสดงในโหมดเต็มหน้าจอ วิดเจ็ตการเติมข้อความอัตโนมัติจะเติมทั้งหน้าจอ
รูปที่ 2: วิดเจ็ตการเติมข้อความอัตโนมัติในโหมดเต็มหน้าจอ

ลงทะเบียนการเรียกกลับสำหรับผลลัพธ์ของ Intent

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

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            Log.i(TAG, "User canceled autocomplete")
        }
    }

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                Log.i(TAG, "User canceled autocomplete");
            }
        });

รับการคาดคะเนสถานที่โดยใช้โปรแกรม

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

  • ต้องระบุ: สตริง query ที่มีข้อความที่ผู้ใช้พิมพ์
  • แนะนํา: A AutocompleteSessionToken ซึ่งจัดกลุ่มระยะการค้นหาและการเลือกของผู้ใช้เป็นเซสชันที่แยกกัน เพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์คำค้นหา และสิ้นสุดเมื่อผู้ใช้เลือกสถานที่
  • แนะนำ: ออบเจ็กต์ RectangularBounds ซึ่งระบุขอบเขตละติจูดและลองจิจูดเพื่อจำกัดผลลัพธ์ให้แสดงเฉพาะภูมิภาคที่ระบุ
  • ไม่บังคับ: รหัสประเทศแบบ 2 ตัวอักษร (ISO 3166-1 Alpha-2) อย่างน้อย 1 รหัส ซึ่งระบุประเทศที่ควรจำกัดผลการค้นหา

  • ไม่บังคับ: A TypeFilter ซึ่งคุณใช้เพื่อจำกัดผลการค้นหาให้เป็นประเภทสถานที่ที่ระบุได้ ระบบรองรับสถานที่ประเภทต่อไปนี้

    • TypeFilter.GEOCODE – แสดงเฉพาะผลการค้นหาการเข้ารหัสพิกัดภูมิศาสตร์ ไม่ใช่ ธุรกิจ ใช้คำขอนี้เพื่อแยกความแตกต่างของผลลัพธ์ในกรณีที่ระบุตำแหน่ง ซึ่งอาจไม่แน่นอน
    • TypeFilter.ADDRESS - แสดงเฉพาะผลการเติมข้อความอัตโนมัติที่มี ที่อยู่ที่แน่นอน ใช้ประเภทนี้เมื่อคุณทราบว่าผู้ใช้กำลังมองหา ที่อยู่ที่ระบุอย่างครบถ้วน
    • TypeFilter.ESTABLISHMENT – แสดงเฉพาะสถานที่ที่เป็น ธุรกิจ

    • TypeFilter.REGIONS – แสดงเฉพาะสถานที่ที่ตรงกับประเภทใดประเภทหนึ่งต่อไปนี้

    • LOCALITY

    • SUBLOCALITY

    • POSTAL_CODE

    • COUNTRY

    • ADMINISTRATIVE_AREA_LEVEL_1

    • ADMINISTRATIVE_AREA_LEVEL_2

    • TypeFilter.CITIES - แสดงเฉพาะผลลัพธ์ที่ตรงกับ LOCALITY หรือ ADMINISTRATIVE_AREA_LEVEL_3

  • ไม่บังคับ: LatLng ที่ระบุตำแหน่งต้นทางของคำขอ เมื่อคุณเรียกใช้ setOrigin() บริการจะแสดงระยะทางเป็นเมตร (distanceMeters) จากต้นทางที่ระบุ สำหรับการคาดคะเนการเติมข้อความอัตโนมัติแต่ละรายการในการตอบกลับ

ดูข้อมูลเกี่ยวกับประเภทสถานที่ได้ในคำแนะนำเกี่ยวกับประเภทสถานที่

ตัวอย่างด้านล่างแสดงการเรียกที่สมบูรณ์ไปยัง PlacesClient.findAutocompletePredictions()

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

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

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

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

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

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

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

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

จำกัดผลการเติมข้อความอัตโนมัติ

คุณสามารถจำกัดผลการเติมข้อความอัตโนมัติให้แสดงเฉพาะภูมิภาคที่ต้องการ และ/หรือ กรองผลการค้นหาให้แสดงเฉพาะประเภทสถานที่อย่างน้อย 1 ประเภท หรือแสดงเฉพาะประเทศไม่เกิน 5 ประเทศ คุณ สามารถใช้ข้อจำกัดเหล่านี้กับกิจกรรมการเติมข้อความอัตโนมัติ AutocompleteSupportFragmentและ API การเติมข้อความอัตโนมัติแบบเป็นโปรแกรมได้

หากต้องการจำกัดผลลัพธ์ ให้ทำดังนี้

  • หากต้องการต้องการผลลัพธ์ภายในภูมิภาคที่กำหนด ให้เรียกใช้ setLocationBias() (ระบบอาจยังแสดงผลลัพธ์บางรายการจากภายนอกภูมิภาคที่กำหนด)
  • หากต้องการแสดงเฉพาะผลลัพธ์ภายในภูมิภาคที่กำหนด ให้เรียกใช้ setLocationRestriction() (ระบบจะแสดงเฉพาะผลลัพธ์ภายในภูมิภาคที่กำหนด)
  • หากต้องการแสดงเฉพาะผลลัพธ์ที่สอดคล้องกับประเภทสถานที่หนึ่งๆ ให้เรียกใช้ setTypesFilter() (เช่น การระบุ TypeFilter.ADDRESS จะแสดง เฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอน)
  • หากต้องการแสดงเฉพาะผลลัพธ์ภายในประเทศที่ระบุสูงสุด 5 ประเทศ ให้เรียกใช้ setCountries() ต้องส่งประเทศเป็นรหัส ประเทศที่เข้ากันได้กับ ISO 3166-1 Alpha-2 ซึ่งมีอักขระ 2 ตัว

เอนเอียงผลการค้นหาไปยังภูมิภาคที่เฉพาะเจาะจง

หากต้องการให้ผลการเติมข้อความอัตโนมัติเอนเอียงไปทางภูมิภาคที่เฉพาะเจาะจง ให้เรียกใช้ setLocationBias()โดยส่ง RectangularBounds ตัวอย่างโค้ดต่อไปนี้แสดงการเรียกใช้ setLocationBias() ในอินสแตนซ์ Fragment เพื่อให้คำแนะนำในการเติมข้อความอัตโนมัติเป็นภูมิภาคซิดนีย์ ประเทศออสเตรเลีย

Kotlin

        autocompleteFragment.setLocationBias(bounds)

Java

        autocompleteFragment.setLocationBias(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)
                )
        );

จำกัดผลลัพธ์ไว้เฉพาะภูมิภาคที่เฉพาะเจาะจง

หากต้องการจำกัดผลการเติมข้อความอัตโนมัติไว้เฉพาะในภูมิภาคที่กำหนด ให้เรียกใช้ setLocationRestriction()โดยส่ง RectangularBounds ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setLocationRestriction() ในอินสแตนซ์ ของ Fragment เพื่อให้คำแนะนำการเติมข้อความอัตโนมัติเป็นภูมิภาคซิดนีย์ ออสเตรเลีย

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

Java

        autocompleteFragment.setLocationRestriction(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)
                )
        );

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

กรองผลลัพธ์ตามประเภทสถานที่หรือคอลเล็กชันประเภท

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

หากต้องการกรองผลการเติมข้อความอัตโนมัติ ให้เรียกใช้ setTypesFilter() เพื่อตั้งค่าตัวกรอง

วิธีกําหนดตัวกรองประเภทหรือคอลเล็กชันประเภท

  • เรียกใช้ setTypesFilter() และระบุค่า type สูงสุด 5 ค่าจากตารางที่ 1 และตารางที่ 2 ที่แสดงในประเภทสถานที่ ค่าประเภทกำหนดโดยค่าคงที่ใน PlaceTypes

  • เรียกใช้ setTypesFilter() และระบุประเภทคอลเล็กชันจากตารางที่ 3 ที่แสดงในประเภทสถานที่ ค่าของคอลเล็กชันกำหนดโดยค่าคงที่ใน PlaceTypes

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

ตัวอย่างโค้ดต่อไปนี้เรียกใช้ setTypesFilter() ใน AutocompleteSupportFragment และระบุค่าประเภทหลายค่า

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setTypesFilter() ใน AutocompleteSupportFragment เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอนโดยการระบุคอลเล็กชันประเภท

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setTypesFilter() ใน IntentBuilder เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ที่มีที่อยู่ที่แน่นอนโดยการระบุคอลเล็กชันประเภท

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .build(this)

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

กรองผลลัพธ์ตามประเทศ

หากต้องการกรองผลการเติมข้อความอัตโนมัติให้เหลือไม่เกิน 5 ประเทศ ให้เรียกใช้ setCountries() เพื่อตั้งค่ารหัสประเทศ จากนั้นส่งตัวกรองไปยัง Fragment หรือ Intent ต้องส่งประเทศเป็นรหัส ประเทศที่เข้ากันได้กับ ISO 3166-1 Alpha-2 ซึ่งมีอักขระ 2 ตัว

ตัวอย่างโค้ดต่อไปนี้แสดงการเรียก setCountries() ใน AutocompleteSupportFragment เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ภายใน ประเทศที่ระบุ

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

Java

    autocompleteFragment.setCountries("AU", "NZ");

ขีดจำกัดการใช้งาน

การใช้งาน Places API รวมถึง Places SDK สำหรับ Android ของคุณ จะไม่มีการจำกัดจำนวนคำขอสูงสุดต่อวัน (QPD) อีกต่อไป อย่างไรก็ตาม ขีดจำกัดการใช้งานต่อไปนี้จะยังคงมีผล

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

แสดงการระบุแหล่งที่มาในแอป

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

ดูรายละเอียดเพิ่มเติมได้ในเอกสารประกอบเกี่ยวกับการระบุแหล่งที่มา

การเพิ่มประสิทธิภาพการเติมข้อความอัตโนมัติของสถานที่ (เดิม)

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

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

แนวทางปฏิบัติแนะนำในการใช้ต้นทุนให้เกิดประโยชน์สูงสุด

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

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

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

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

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

แอปพลิเคชันของคุณต้องใช้ข้อมูลอื่นนอกเหนือจากที่อยู่และละติจูด/ลองจิจูดของการคาดคะเนที่เลือกไหม

ใช่ ต้องระบุรายละเอียดเพิ่มเติม

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

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

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

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

ไม่ ต้องใช้แค่ที่อยู่และสถานที่

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

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

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

ใช่

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

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

ไม่

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

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

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

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

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

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

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

  1. ดูค่าใช้จ่ายได้ที่รายการราคาของ Google Maps Platform

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

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

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

การแก้ปัญหา

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

ข้อผิดพลาดที่เกิดขึ้นในการใช้ตัวควบคุมการเติมข้อความอัตโนมัติจะแสดงในonActivityResult() Callback โทรหา Autocomplete.getStatus() เพื่อรับข้อความสถานะ สำหรับผลลัพธ์