Place Autocomplete

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

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

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

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

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

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

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

ตัวเลือกที่ 1: ฝังการเติมข้อความอัตโนมัติที่รองรับ

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

1. เพิ่มส่วนย่อยลงในเลย์เอาต์ XML ของกิจกรรม
2. เพิ่ม Listener ให้กับกิจกรรมหรือส่วนย่อย

เพิ่มการเติมข้อความอัตโนมัติในการสนับสนุนกิจกรรม

หากต้องการเพิ่ม 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 มิเช่นนั้น Fragment จะทํางานไม่ถูกต้อง

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

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

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

      

    // 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 ที่ต้องการ Intent ต้องเรียกใช้ startActivityForResult โดยส่งผ่านโค้ดคําขอที่ระบุ Intent
2. ลบล้างการเรียกกลับ onActivityResult เพื่อรับสถานที่ที่เลือก

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

ตัวอย่างด้านล่างแสดงการใช้ Autocomplete.IntentBuilder เพื่อสร้าง Intent ที่จะเปิดวิดเจ็ตการเติมข้อความอัตโนมัติเป็นความตั้งใจ

    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

ลบล้างโค้ดเรียกกลับ onActivityResult

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

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

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

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

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

• ไม่บังคับ: TypeFilter ซึ่งใช้จํากัดผลการค้นหาให้แสดงเฉพาะประเภทสถานที่ที่ระบุได้ ประเภทสถานที่ต่อไปนี้รองรับ

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

  • TypeFilter.REGIONS – แสดงเฉพาะสถานที่ที่ตรงกับประเภทอย่างใดอย่างหนึ่งต่อไปนี้

    • LOCALITY
    • SUBLOCALITY
    • POSTAL_CODE
    • COUNTRY
    • ADMINISTRATIVE_AREA_LEVEL_1
    • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES – แสดงเฉพาะผลลัพธ์ที่ตรงกับ LOCALITY หรือ ADMINISTRATIVE_AREA_LEVEL_3

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

สําหรับข้อมูลเกี่ยวกับประเภทสถานที่ โปรดดูคู่มือประเภทสถานที่

ตัวอย่างด้านล่างแสดงการโทรที่สมบูรณ์ไปยัง PlacesClient.findAutocompletePredictions()

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

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

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

      

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

      

จํากัดผลการค้นหาเฉพาะภูมิภาค

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

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

      

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

      

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

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

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

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

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

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

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

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

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

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

      

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

      

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

    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

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

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

      

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

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

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

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

      

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

      

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

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

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

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

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

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

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

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

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

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

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

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

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

การใช้ต้นทุนขั้นสูง

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

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

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

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

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

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

การแก้ปัญหา

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

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