Place Autocomplete

เลือกแพลตฟอร์ม: Android iOS JavaScript บริการเว็บ

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

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

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

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

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

ตัวเลือกที่ 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

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

Java


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

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

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

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

ตัวอย่างด้านล่างใช้ Autocomplete.IntentBuilder ในการสร้างความตั้งใจในการเปิดใช้วิดเจ็ตการเติมข้อความอัตโนมัติเป็น 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.NAME)

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

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

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

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

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

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

Kotlin



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

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);
                    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 ซึ่งระบุขอบเขตละติจูดและลองจิจูดเพื่อจำกัดผลลัพธ์ไปยังภูมิภาคที่ระบุ
  • ไม่บังคับ: รหัสประเทศ 2 ตัวอักษรขึ้นไป (ISO 3166-1 Alpha-2) ซึ่งระบุประเทศที่ควรจำกัดผลการค้นหา

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

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(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) แสดงข้อความทั้งหมดของคำอธิบายสถานที่ ซึ่งจะเป็นการรวมข้อความหลัก และข้อความรอง ตัวอย่างเช่น "Eiffel Tower, Avenue Anatole France, Paris, France" นอกจากนี้ วิธีนี้ยังช่วยให้คุณไฮไลต์ส่วนของคำอธิบายที่ตรงกับการค้นหาด้วยสไตล์ที่คุณต้องการได้โดยใช้ CharacterStyle คุณจะระบุพารามิเตอร์ CharacterStyle หรือไม่ก็ได้ ตั้งค่าให้เป็น Null หากไม่ต้องการไฮไลต์
  • getPrimaryText(CharacterStyle) แสดงข้อความหลักที่อธิบายสถานที่ ซึ่งปกติจะเป็นชื่อของสถานที่ ตัวอย่างเช่น "Eiffel Tower" และ "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() ต้องส่งประเทศเป็นอักขระ 2 ตัวตามมาตรฐาน ISO 3166-1 รหัสประเทศที่ใช้ได้กับ Alpha-2

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

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

Kotlin



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

Java


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

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

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

Kotlin



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

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 ซึ่งแสดงใน Place Types ค่าประเภทจะกำหนดโดยค่าคงที่ใน PlaceTypes

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

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

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

Kotlin



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

Java


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

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

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java


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

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

Kotlin



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

Java


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

Kotlin



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

Java


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ไม่ ต้องใช้เฉพาะที่อยู่และตำแหน่งเท่านั้น

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

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

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

ได้

ใช้การเติมข้อความอัตโนมัติในสถานที่แบบเป็นโปรแกรมโดยไม่ต้องใช้โทเค็นเซสชันและเรียกใช้ Geocoding API ในการคาดการณ์สถานที่ที่เลือก
Geocoding API จะส่งที่อยู่และพิกัดละติจูด/ลองจิจูดในราคา $0.005 ต่อคำขอ การส่งคำขอเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ - ต่อคำขอ 4 รายการมีค่าใช้จ่าย $0.01132 ดังนั้นค่าใช้จ่ายทั้งหมดของคำขอ 4 รายการพร้อมการเรียก Geocoding API เกี่ยวกับการคาดการณ์สถานที่ที่เลือกจะเป็น $0.01632 ซึ่งต่ำกว่าราคาการเติมข้อความอัตโนมัติต่อเซสชันที่ $0.017 ต่อเซสชัน1

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

ไม่ได้

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

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

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

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

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

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

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

  1. ค่าใช้จ่ายที่แสดงที่นี่เป็นสกุลเงิน USD โปรดดูหน้าการเรียกเก็บเงินของ Google Maps Platform สำหรับข้อมูลราคาทั้งหมด

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

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

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

การแก้ปัญหา

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

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