หน้านี้ได้รับการแปลโดย Cloud Translation API

Place Autocomplete

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

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

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

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

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

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

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

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

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

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

เพิ่มส่วนย่อยในเลย์เอาต์ XML ของกิจกรรม
เพิ่ม 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.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 เพื่อเปิดกิจกรรมการเติมข้อความอัตโนมัติ

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

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

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

สร้าง 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.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);

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

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

เมื่อแสดงในโหมดเต็มหน้าจอ วิดเจ็ตเติมข้อความอัตโนมัติจะแสดงเต็มหน้าจอ — **ภาพที่ 2**: วิดเจ็ตเติมข้อความอัตโนมัติในโหมด FULLSCREEN

ลงทะเบียนโค้ดเรียกกลับสำหรับผลลัพธ์ Intent

หากต้องการรับการแจ้งเตือนเมื่อผู้ใช้เลือกสถานที่ ให้กำหนด registerForActivityResult() Launcher ซึ่งจะเปิดกิจกรรมและจัดการผลลัพธ์ตามที่แสดงในตัวอย่างต่อไปนี้ด้วย หากผู้ใช้เลือกการคาดการณ์ ระบบจะส่งการคาดการณ์ใน 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 ตัวอักษรอย่างน้อย 1 ตัว (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) แสดงข้อความหลักที่อธิบายถึงสถานที่ ซึ่งโดยปกติจะเป็นชื่อของสถานที่นี้ เช่น "หอไอเฟล" และ "123 ถนนพิตต์"
getSecondaryText(CharacterStyle) แสดงข้อความบริษัทในเครือของคำอธิบายสถานที่ ซึ่งจะเป็นประโยชน์ เช่น แสดงเป็นบรรทัดที่ 2 เมื่อแสดงการคาดคะเนเพื่อเติมข้อความอัตโนมัติ ตัวอย่างเช่น "Avenue Anatole France, Paris, France" และ "Sydney, New South Wales"
getPlaceId() แสดงรหัสของสถานที่ที่คาดไว้ รหัสสถานที่คือตัวระบุแบบข้อความที่ระบุสถานที่อย่างไม่ซ้ำกัน ซึ่งคุณใช้เพื่อเรียกออบเจ็กต์ Place อีกครั้งในภายหลังได้ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับรหัสสถานที่ใน Places SDK สำหรับ Android โปรดดูรายละเอียด สถานที่ ดูข้อมูลทั่วไปเกี่ยวกับรหัสสถานที่ได้ที่ภาพรวมรหัสสถานที่
getPlaceTypes() แสดงรายการประเภทสถานที่ที่เกี่ยวข้องกับสถานที่นี้
getDistanceMeters() จะแสดงผลระยะทางเส้นตรงเป็นเมตรระหว่างสถานที่นี้กับต้นทางที่ระบุในคำขอ

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

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

โทเค็นเซสชันจะจัดกลุ่มเฟสการค้นหาและการเลือกของการค้นหาในการเติมข้อความอัตโนมัติของผู้ใช้ลงในเซสชันที่แยกกันเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์ข้อความค้นหา และสรุปเมื่อผู้ใช้เลือกสถานที่ แต่ละเซสชันสามารถมีข้อความค้นหาได้หลายรายการ ตามด้วยการเลือกสถานที่เพียงแห่งเดียว เมื่อเซสชันสิ้นสุดลง โทเค็นจะใช้ไม่ได้อีกต่อไป แอปของคุณต้องสร้างโทเค็นใหม่สำหรับแต่ละเซสชัน เราขอแนะนำให้ใช้โทเค็นเซสชันสำหรับเซสชันการเติมข้อความอัตโนมัติแบบเป็นโปรแกรมทั้งหมด (เมื่อคุณฝังส่วนย่อยหรือเปิดการเติมข้อความอัตโนมัติโดยใช้ 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() บนอินสแตนซ์ Fragment เพื่ออคติคำแนะนำการเติมข้อความอัตโนมัติไปยังภูมิภาคของซิดนีย์ ประเทศออสเตรเลีย

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 ที่แสดงในส่วนประเภทสถานที่ ค่าประเภทจะกำหนดโดยค่าคงที่ใน PlaceTypes
เรียกใช้ setTypesFilter() และระบุคอลเล็กชันประเภทจากตาราง 3 ที่แสดงในประเภทสถานที่ ค่าคอลเล็กชันจะกำหนดโดยค่าคงที่ใน PlaceTypes

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

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

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 ต้องส่งประเทศเป็นรหัสประเทศที่เข้ากันได้กับ 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
หากแอปของคุณใช้วิดเจ็ตการเติมข้อความอัตโนมัติ คุณไม่จำเป็นต้องดำเนินการใดๆ เพิ่มเติม (การระบุแหล่งที่มาที่จำเป็นจะแสดงโดยค่าเริ่มต้น)
หากคุณดึงและแสดงข้อมูลสถานที่เพิ่มเติมหลังจากได้รับสถานที่โดยใช้รหัส คุณต้องแสดงการระบุแหล่งที่มาของบุคคลที่สามด้วย

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

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

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

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

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

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

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

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

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

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

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

หากต้องการความช่วยเหลือในการเลือกการใช้งานฟีเจอร์ "สถานที่อัตโนมัติ" ที่ตรงกับความต้องการของคุณ ให้เลือกแท็บที่ตรงกับคําตอบสําหรับคําถามต่อไปนี้

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

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

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

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

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

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

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

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

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

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

มี

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

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

ไม่ได้

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

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

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

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

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

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

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

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

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

การแก้ปัญหา

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

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