Place Autocomplete

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

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

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

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

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

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

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

  1. ใช้ Autocomplete.IntentBuilder เพื่อสร้าง Intent โดยส่งโหมด Autocomplete ที่ต้องการ
  2. กําหนดตัวเปิดใช้งานผลการค้นหากิจกรรม 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: วิดเจ็ตการเติมข้อความอัตโนมัติในโหมดเต็มหน้าจอ

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

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

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

  • ต้องระบุ: สตริง query ที่มีข้อความที่ผู้ใช้พิมพ์
  • แนะนํา: 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() ที่สมบูรณ์

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

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() ในอินสแตนซ์ของฟragment เพื่อกำหนดให้คำแนะนำการเติมข้อความอัตโนมัติเอนเอียงไปยังภูมิภาคซิดนีย์ในออสเตรเลีย

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

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

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

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

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

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

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

การใช้ต้นทุนให้เกิดประโยชน์สูงสุดขั้นพื้นฐาน

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ใช่

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

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

ไม่

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

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

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

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

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

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

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

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

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

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

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

การแก้ปัญหา

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

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