Place Autocomplete

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

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

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

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

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

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

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

ตัวเลือกที่ 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
• หากคุณใช้ Autocomplete Fragment และต้องการลบล้าง onActivityResult คุณต้องเรียกใช้ super.onActivityResult มิฉะนั้น Fragment จะทํางานไม่ถูกต้อง

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

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

    // 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")
        }
    })

      

    // 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

    // 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)

      

    // 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 เพื่อเปิดวิดเจ็ตการเติมข้อความอัตโนมัติ คุณจะเลือกจาก โหมดการแสดงผลแบบซ้อนทับหรือแบบเต็มหน้าจอได้ ภาพหน้าจอต่อไปนี้แสดงโหมดการแสดงผลแต่ละโหมดตามลำดับ

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

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

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")
        }
    }

      

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 รหัส ซึ่งระบุประเทศที่ควรจำกัดผลการค้นหา

• ไม่บังคับ: 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()

    // 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)
            }
        }

      

    // 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) แสดงข้อความทั้งหมดของคำอธิบายสถานที่ นี่คือข้อความหลักและข้อความรองรวมกัน ตัวอย่าง: "Eiffel Tower, Avenue Anatole France, Paris, 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 เพื่อให้คำแนะนำในการเติมข้อความอัตโนมัติเป็นภูมิภาคซิดนีย์ ประเทศออสเตรเลีย

        autocompleteFragment.setLocationBias(bounds)

      

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

      

จำกัดผลการค้นหาให้แสดงเฉพาะในภูมิภาคที่เฉพาะเจาะจง

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

        autocompleteFragment.setLocationRestriction(bounds)

      

        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 และระบุค่าประเภทหลายค่า

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

      

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

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

    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 เพื่อตั้งค่าตัวกรองที่แสดงเฉพาะผลลัพธ์ภายในประเทศที่ระบุ

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

      

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

      

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

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

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

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

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

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

การเพิ่มประสิทธิภาพ Place Autocomplete (เดิม)

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

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

• วิธีที่เร็วที่สุดในการพัฒนาอินเทอร์เฟซผู้ใช้ที่ใช้งานได้คือการใช้ Maps JavaScript API วิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ (เดิม) Places SDK สำหรับ Android วิดเจ็ตการเติมข้อความอัตโนมัติของสถานที่ (เดิม) หรือ Places SDK สำหรับ iOS การควบคุม UI การเติมข้อความอัตโนมัติของสถานที่ (เดิม)
• ทำความเข้าใจฟิลด์ข้อมูลที่จำเป็นของ การเติมข้อความอัตโนมัติของสถานที่ (เดิม) ตั้งแต่เริ่มต้น
• ฟิลด์การเอนเอียงตามสถานที่ตั้งและข้อจำกัดด้านสถานที่ตั้งเป็นฟิลด์ที่ไม่บังคับ แต่ก็อาจ ส่งผลต่อประสิทธิภาพการเติมข้อความอัตโนมัติอย่างมาก
• ใช้การจัดการข้อผิดพลาดเพื่อให้แน่ใจว่าแอปของคุณจะลดประสิทธิภาพลงอย่างราบรื่น หาก API แสดงข้อผิดพลาด
• ตรวจสอบว่าแอปของคุณจัดการเมื่อไม่มีการเลือกและเสนอวิธีให้ผู้ใช้ ดำเนินการต่อ

แนวทางปฏิบัติแนะนำในการเพิ่มประสิทธิภาพต้นทุน

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

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

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

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

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

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

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

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

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

การปรับตำแหน่ง

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

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

จำกัดผลลัพธ์ให้อยู่ในพื้นที่ที่ระบุโดยส่งพารามิเตอร์ locationRestriction

นอกจากนี้ คุณยังจำกัดผลลัพธ์ให้แสดงเฉพาะภูมิภาคที่กำหนดโดย location และพารามิเตอร์ radius ได้ด้วยโดยการเพิ่มพารามิเตอร์ strictbounds ซึ่งจะสั่งให้การเติมข้อความอัตโนมัติของสถานที่ (เดิม) แสดงเฉพาะ ผลลัพธ์ภายในภูมิภาคนั้น

การแก้ปัญหา

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

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