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

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

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

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

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

แทน

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

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

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

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

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)

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

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

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

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

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

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

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

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

  • จําเป็น: สตริง query ที่มีข้อความที่ผู้ใช้พิมพ์
  • แนะนํา: AutocompleteSessionToken ซึ่งจัดกลุ่มคําค้นหาและเฟสการเลือกของคําค้นหาของผู้ใช้เป็นเซสชันที่ไม่มีการแบ่งแยกเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์คําค้นหา และสรุปเมื่อเลือกสถานที่
  • แนะนํา: ออบเจ็กต์ RectangularBounds ซึ่งระบุขอบเขตละติจูดและลองจิจูดเพื่อจํากัดผลลัพธ์ไปยังภูมิภาคที่ระบุ
  • ไม่บังคับ: รหัสประเทศ 2 ตัวอักษร 1 ตัวอักษรขึ้นไป (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() ที่สมบูรณ์

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());
        }
    });

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

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() แสดงผลระยะทางเป็นเส้นตรงเป็นหน่วยเมตรระหว่างสถานที่นี้และ ต้นทางที่ระบุในคําขอ

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

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

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

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

จํากัดผลลัพธ์ของการเติมข้อความอัตโนมัติ

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

หากต้องการจํากัดผลการค้นหา ให้ทําดังนี้

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

การให้น้ําหนักผลลัพธ์กับภูมิภาคที่ระบุ

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

Java


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

Kotlin


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

จํากัดผลลัพธ์เฉพาะภูมิภาค

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

Java


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

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            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 และระบุค่าหลายค่า

Java


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

Kotlin


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

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

Java


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

Kotlin


    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

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

Java


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

Kotlin


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

กรองผลการค้นหาตามประเทศ

หากต้องการกรองผลลัพธ์การเติมข้อความอัตโนมัติสูงสุด 5 ประเทศ โปรดโทร setCountries() เพื่อตั้งค่ารหัสประเทศ จากนั้นส่งผ่านตัวกรองไปยังส่วนย่อยหรือความตั้งใจ ประเทศต้องส่งผ่านเป็นรหัสประเทศ ISO 3166-1 Alpha-2 ที่เข้ากันได้แบบ 2 อักขระ

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

Java


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

Kotlin


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

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

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

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

แสดงแอตทริบิวต์ในแอป

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ใช่

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

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

ไม่ได้

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

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

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

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

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

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

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

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

แนวทางปฏิบัติแนะนําสําหรับประสิทธิภาพ

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

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

การแก้ปัญหา

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

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