Place Autocomplete

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

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

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

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

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

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

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

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

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

เพิ่ม AutoAutoSupportFragment ไปยังกิจกรรม

หากต้องการเพิ่ม 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 ของคุณ:

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

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

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

Java


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

      

Kotlin


    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 เพื่อเปิดวิดเจ็ตเติมข้อความอัตโนมัติ คุณจะเลือกจากโหมดการแสดงผลซ้อนทับหรือโหมดเต็มหน้าจอ ภาพหน้าจอต่อไปนี้แสดงแต่ละโหมดการแสดงผลตามลําดับ

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

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

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

Java


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

      

Kotlin


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 ตัวอักษรอย่างน้อย 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(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());
        }
    });

      

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

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

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

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

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

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

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

ในการจํากัดผลลัพธ์ ให้ทําดังนี้

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

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

    อนุญาตให้มีคําขอเพียง 1 ประเภทจากตาราง 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(TypeFilter.ADDRESS.toString()));

      

Kotlin


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

      

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

Java


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

      

Kotlin


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

      

กรองผลลัพธ์ตามประเทศ

หากต้องการกรองผลลัพธ์ในการเติมข้อความอัตโนมัติสูงสุด 5 ประเทศ ให้โทร setCountries() เพื่อตั้งค่ารหัสประเทศ จากนั้นส่งผ่านตัวกรองไปยังส่วนย่อยหรือ Intent ประเทศต้องส่งผ่านเป็นรหัสประเทศ 2 อักขระตามมาตรฐาน ISO 3166-1 Alpha-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, Places Android Auto วิดเจ็ตการเติมข้อความอัตโนมัติ หรือการควบคุม UI ของการเติมข้อความอัตโนมัติใน Places SDK สําหรับ iOS
  • พัฒนาการทําความเข้าใจช่องข้อมูลการเติมข้อความอัตโนมัติที่สําคัญในตอนต้น
  • ช่องการให้น้ําหนักตําแหน่งและข้อจํากัดด้านตําแหน่งเป็นตัวเลือกที่ไม่บังคับ แต่อาจมีผลกระทบอย่างมากต่อประสิทธิภาพการเติมข้อความอัตโนมัติ
  • ใช้การจัดการข้อผิดพลาดเพื่อให้แน่ใจว่าแอปของคุณมีประสิทธิภาพลดลงหาก API แสดงผลข้อผิดพลาด
  • ตรวจสอบว่าแอปรองรับเมื่อไม่มีการเลือกและเสนอวิธีดําเนินการต่อแก่ผู้ใช้

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ใช่

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

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

ไม่ได้

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

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

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

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

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

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

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


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

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

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

  • เพิ่มข้อจํากัดด้านประเทศ การให้น้ําหนักตําแหน่ง และค่ากําหนด (สําหรับการติดตั้งใช้งานแบบเป็นโปรแกรม) ให้กับการติดตั้งใช้งานการเติมข้อความอัตโนมัติเกี่ยวกับสถานที่ ค่ากําหนดภาษาไม่จําเป็นต้องใช้วิดเจ็ตเนื่องจากเลือกค่ากําหนดภาษาจากเบราว์เซอร์หรืออุปกรณ์เคลื่อนที่ของผู้ใช้
  • หากการเติมข้อความอัตโนมัติของสถานที่มีแผนที่รวมอยู่ด้วย คุณสามารถจัดตําแหน่งการให้น้ําหนักตามวิวพอร์ตของแผนที่ได้
  • ในสถานการณ์ที่ผู้ใช้ไม่ได้เลือกการคาดคะเนการเติมข้อความอัตโนมัติ โดยทั่วไปแล้วเป็นเพราะการคาดคะเนดังกล่าวไม่ใช่ที่อยู่ผลลัพธ์ที่ต้องการ คุณจึงนําอินพุตของผู้ใช้เดิมมาใช้ซ้ําได้เพื่อให้ได้ผลลัพธ์ที่เกี่ยวข้องมากขึ้น ดังนี้
    • หากคุณคาดว่าผู้ใช้จะป้อนเฉพาะข้อมูลที่อยู่ ให้ใช้อินพุตเดิมของผู้ใช้ซ้ําในการเรียก Geocoding API
    • หากคุณคาดว่าผู้ใช้จะป้อนการค้นหาสถานที่ตามชื่อหรือที่อยู่ ให้ใช้ค้นหาสถานที่ หากผลลัพธ์คาดหวังในภูมิภาคใดภูมิภาคหนึ่งโดยเฉพาะ ให้ใช้การให้น้ําหนักตําแหน่ง
    สถานการณ์อื่นๆ ที่ดีที่สุดคือการเปลี่ยนไปใช้ Geocoding API ได้แก่
    • ผู้ใช้ป้อนที่อยู่ย่อยในประเทศอื่นๆ นอกเหนือจากออสเตรเลีย นิวซีแลนด์ หรือแคนาดา เช่น ที่อยู่ "123 Bowdoin St #456, Boston MA, USA" ในสหรัฐอเมริกาไม่รองรับการเติมข้อความอัตโนมัติ (การเติมข้อความอัตโนมัติรองรับที่อยู่ย่อยเฉพาะในออสเตรเลีย นิวซีแลนด์ และแคนาดาเท่านั้น รูปแบบที่อยู่ที่รองรับใน 3 ประเทศ ได้แก่ "9/321 Pitt Street, Sydney, New South Wales, Australia" หรือ "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" หรือ "145-112 Renfrew Dr, Markham, Ontario, Canada")
    • ผู้ใช้ป้อนที่อยู่ที่มีส่วนถนน เช่น "23-30 29th St, Queens" ในนิวยอร์กซิตี้ หรือ "47-380 Kamehameha Hwy, Kaneohe" บนเกาะคาไวใน Hawai'i

การแก้ปัญหา

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

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