Place Autocomplete

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

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

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

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

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

การเพิ่มวิดเจ็ตการเติมข้อความอัตโนมัติลงในแอปทำได้ 2 วิธีดังนี้

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

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

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

1. เพิ่มข้อมูลโค้ดไปยังเลย์เอาต์ XML ของกิจกรรม
2. เพิ่ม Listener ลงในกิจกรรมหรือแฟรกเมนต์

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

หากต้องการเพิ่ม AutocompleteSupportFragment ในกิจกรรม ให้เพิ่มส่วนย่อยใหม่ลงใน เลย์เอาต์ 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"
  />

• ส่วนย่อยที่ไม่มีเส้นขอบหรือพื้นหลังโดยค่าเริ่มต้น หากต้องการจัดเตรียม รูปลักษณ์ที่สอดคล้องกัน ฝังส่วนย่อยภายในเลย์เอาต์อื่น องค์ประกอบ เช่น CardView
• หากคุณกำลังใช้ส่วนการเติมข้อความอัตโนมัติและจำเป็นต้องลบล้าง onActivityResult คุณต้องเรียกใช้ super.onActivityResult ไม่เช่นนั้น ส่วนย่อยทำงานไม่ถูกต้อง

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

PlaceSelectionListener จะจัดการการแสดงสถานที่ตามการเลือกของผู้ใช้ โค้ดต่อไปนี้จะแสดงการสร้างการอ้างอิงไปยังส่วนย่อยและ กำลังเพิ่ม 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.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            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.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(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.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .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.NAME);

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

      

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

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

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

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            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);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

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

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

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

• ไม่บังคับ: ตอบ 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.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

    // 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(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

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

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

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

โทเค็นเซสชัน

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

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

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

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

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

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

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

ผลลัพธ์การให้น้ำหนักพิเศษกับภูมิภาคที่เฉพาะเจาะจง

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

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

      

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

      

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

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

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

      

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

      

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

กรองผลการค้นหาตามประเภทสถานที่หรือการรวบรวมประเภท

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

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

ในการระบุประเภทหรือตัวกรองคอลเล็กชัน

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

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

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

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

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

      

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

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

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

      

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

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

ในการกรองผลลัพธ์ของการเติมข้อความอัตโนมัติได้สูงสุดถึง 5 ประเทศ ให้โทรหา setCountries() เพื่อตั้งค่ารหัสประเทศ จากนั้นส่งตัวกรองไปยังส่วนย่อยหรือ Intent คุณต้องส่งประเทศเป็นรหัสประเทศแบบ 2 อักขระที่เข้ากันได้กับ ISO 3166-1 Alpha-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 หรือการควบคุม UI การเติมข้อความอัตโนมัติของ Places SDK สำหรับ iOS
• ทําความเข้าใจช่องข้อมูลการเติมข้อความอัตโนมัติของสถานที่สําคัญตั้งแต่เริ่มต้น
• ฟิลด์การให้น้ำหนักสถานที่และการจำกัดตำแหน่งเป็นฟิลด์ที่ไม่บังคับแต่สามารถใส่ได้ จะมีผลอย่างมากต่อประสิทธิภาพการเติมข้อความอัตโนมัติ
• ใช้การจัดการข้อผิดพลาดเพื่อให้แอปทำงานได้อย่างราบรื่นหาก API แสดงข้อผิดพลาด
• ตรวจสอบว่าแอปของคุณแฮนเดิลเมื่อไม่ได้เลือกและเสนอทางเลือกให้กับผู้ใช้ เพื่อดำเนินการต่อ

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

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

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

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

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

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

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

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

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

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

การแก้ปัญหา

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

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