Place Autocomplete

플랫폼 선택: Android iOS JavaScript 웹 서비스

Android용 Places SDK의 자동 완성 서비스는 사용자 검색어에 대한 응답으로 장소 예상 검색어를 반환합니다. 사용자가 입력할 때 자동 완성 서비스는 비즈니스, 주소, 플러스 코드, 관심 장소 등의 장소를 추천해 줍니다.

다음과 같은 방식으로 자동완성을 앱에 추가할 수 있습니다.

자동 완성 위젯 추가

자동 완성 위젯은 자동 완성 기능이 내장된 검색 대화상자입니다. 사용자가 검색어를 입력할 때 위젯은 선택할 수 있는 예상 장소의 목록을 표시합니다. 사용자가 선택하면 Place 인스턴스가 반환되며 앱은 이 인스턴스를 사용하여 선택된 장소에 관한 세부정보를 가져올 수 있습니다.

자동완성 위젯을 앱에 추가하기 위한 두 가지 옵션이 있습니다.

옵션 1: AutocompleteSupportFragment 삽입

앱에 AutocompleteSupportFragment를 추가하려면 다음 단계를 따르세요.

  1. 프래그먼트를 활동의 XML 레이아웃에 추가합니다.
  2. 활동 또는 프래그먼트에 리스너를 추가합니다.

활동에 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는 사용자의 선택에 대한 응답으로 장소를 반환하는 작업을 처리합니다. 다음 코드는 프래그먼트 참조를 만들고 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: 인텐트를 사용하여 자동 완성 활동 실행

앱에서 다른 탐색 흐름을 사용하려면 (예: 검색창이 아닌 아이콘에서 자동 완성 환경을 트리거) 인텐트를 사용하여 자동 완성을 실행하면 됩니다.

인텐트를 사용하여 자동완성 위젯을 실행하려면, 다음 단계를 따르세요.

  1. Autocomplete.IntentBuilder를 사용하여 인텐트를 만들고 원하는 Autocomplete 모드를 전달합니다.
  2. 인텐트를 실행하고 사용자가 선택한 장소 예상 검색어를 결과에서 처리하는 데 사용할 수 있는 활동 결과 런처 registerForActivityResult를 정의합니다.

자동 완성 인텐트 만들기

아래 예에서는 Autocomplete.IntentBuilder를 사용하여 자동 완성 위젯을 인텐트로 실행하는 인텐트를 만듭니다.

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

      

인텐트를 사용하여 자동 완성 위젯을 실행할 때 오버레이 또는 전체 화면 표시 모드 중에서 선택할 수 있습니다. 다음 스크린샷은 각 표시 모드를 보여줍니다.

오버레이 모드로 표시되면 자동 완성 위젯이 호출 UI 위에 중첩되어 표시됩니다.
그림 1: OVERLAY 모드의 자동 완성 위젯
자동 완성 위젯이 전체 화면 모드로 표시되면 전체 화면을 채웁니다.
그림 2: 전체 화면 모드의 자동 완성 위젯

인텐트 결과에 콜백 등록

사용자가 장소를 선택할 때 알림을 수신하려면 다음 예와 같이 활동을 실행하고 결과를 처리하는 registerForActivityResult() 런처를 정의합니다. 사용자가 예상 검색어를 선택하면 결과 객체에 포함된 인텐트로 전송됩니다. 인텐트는 Autocomplete.IntentBuilder에 의해 빌드되었으므로 메서드 Autocomplete.getPlaceFromIntent()는 인텐트에서 Place 객체를 추출할 수 있습니다.

Kotlin



private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java


private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

프로그래매틱 방식으로 장소 예상 검색어 가져오기

자동 완성 위젯에서 제공하는 UI 대신 맞춤 검색 UI를 만들 수 있습니다. 이렇게 하려면 앱에서 프로그래매틱 방식으로 장소 예상 검색어를 가져와야 합니다. 앱은 PlacesClient.findAutocompletePredictions()를 호출하고 다음 매개변수와 함께 FindAutocompletePredictionsRequest 객체를 전달하여 Autocomplete API에서 예상 장소 이름 및 주소 목록을 가져올 수 있습니다.

  • 필수: 사용자가 입력한 텍스트를 포함하는 query 문자열입니다.
  • 권장: 결제 목적으로 사용자 검색의 쿼리 및 선택 단계를 별개의 세션으로 그룹화하는 AutocompleteSessionToken입니다. 세션은 사용자가 쿼리를 입력하기 시작하면 시작되고 장소를 선택하면 종료됩니다
  • 권장: 결과를 지정된 지역으로 제한하기 위해 위도 및 경도 경계를 지정하는 RectangularBounds 객체.
  • 선택사항: 결과를 제한해야 하는 국가를 나타내는 하나 이상의 두 글자 국가 코드 (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.CITIESLOCALITY 또는 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는 TaskFindAutocompletePredictionsResponse를 반환합니다. FindAutocompletePredictionsResponse에는 예상 장소를 나타내는 AutocompletePrediction 객체의 목록이 포함됩니다. 쿼리 및 필터 기준에 해당하는 알려진 장소가 없으면 목록이 비어 있을 수 있습니다.

각 예상 장소에 대해 다음 메서드를 호출하여 장소 세부정보를 가져올 수 있습니다.

  • getFullText(CharacterStyle)는 장소 설명의 전체 텍스트를 반환합니다. 이 텍스트는 기본 텍스트와 보조 텍스트의 조합입니다. 예: 'Eiffel Tower, Avenue Anatole France, Paaris, France'. 또한 이 메서드를 사용하면 CharacterStyle를 사용하여 원하는 스타일로 검색어와 일치하는 설명 섹션을 강조표시할 수 있습니다. CharacterStyle 매개변수는 선택사항입니다. 강조 표시가 필요없는 경우는 null로 설정하세요.
  • getPrimaryText(CharacterStyle)는 장소를 설명하는 기본 텍스트를 반환합니다. 일반적으로 장소의 이름입니다. 예: 'Eiffel Tower' 및 '123 Pitt Street'.
  • getSecondaryText(CharacterStyle)는 장소 설명의 보조 텍스트를 반환합니다. 예를 들어 자동 완성 예상 검색어를 표시할 때 두 번째 줄로 유용합니다. 예: 'Avenue Anatole France, Paris, France' 및 'Sydney, New South Wales'.
  • getPlaceId()는 예상 장소의 장소 ID를 반환합니다. 장소 ID는 장소를 고유하게 나타내는 텍스트 식별자로, 나중에 Place 객체를 다시 가져오는 데 사용할 수 있습니다. Android용 Places SDK의 장소 ID에 대한 자세한 내용은 장소 세부정보를 참고하세요. 장소 ID에 대한 일반적인 정보는 장소 ID 개요를 참고하세요.
  • getPlaceTypes()는 이 장소와 연결된 장소 유형 목록을 반환합니다.
  • getDistanceMeters()는 이 장소와 요청에 지정된 출발지 사이의 직선 거리를 미터 단위로 반환합니다.

세션 토큰

세션 토큰은 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션은 사용자가 쿼리를 입력하기 시작하면 시작되고 장소를 선택하면 종료됩니다. 세션마다 여러 개의 쿼리가 포함될 수 있으며 하나의 장소가 선택됩니다. 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱은 각 세션에 대해 새 토큰을 생성해야 합니다. 모든 프로그래매틱 자동 완성 세션에 세션 토큰을 사용하는 것이 좋습니다. 프래그먼트를 삽입하거나 인텐트를 사용하여 자동 완성을 실행하면 API가 이 작업을 자동으로 처리합니다.

Android용 Places SDK는 AutocompleteSessionToken를 사용하여 각 세션을 식별합니다. 앱은 새 세션을 시작할 때마다 새 세션 토큰을 전달한 다음 후속 fetchPlace() 호출에서 장소 ID와 함께 동일한 토큰을 전달하여 사용자가 선택한 장소의 장소 세부정보를 가져와야 합니다.

세션 토큰에 대해 자세히 알아보세요.

자동 완성 결과 제한

자동 완성 결과를 특정 지역으로 제한하거나 하나 이상의 장소 유형 또는 최대 5개의 국가로 결과를 필터링할 수 있습니다. 이러한 제약 조건은 자동 완성 활동, AutocompleteSupportFragment, 프로그래매틱 자동 완성 API에 적용할 수 있습니다.

결과를 제한하려면 다음 단계를 따르세요.

  • 정의된 지역 내의 결과를 선호하려면 setLocationBias()를 호출합니다(정의된 지역 외부의 일부 결과는 여전히 반환될 수 있음).
  • 정의된 리전 내의 결과만 표시하려면 setLocationRestriction()를 호출합니다 (정의된 리전 내의 결과만 반환됨).
  • 특정 장소 유형을 준수하는 결과만 반환하려면 setTypesFilter()를 호출합니다. 예를 들어 TypeFilter.ADDRESS를 지정하면 정확한 주소를 가진 결과만 반환됩니다.
  • 지정된 최대 5개 국가의 결과만 반환하려면 setCountries()를 호출합니다. 국가는 2자리 ISO 3166-1 Alpha-2 호환 국가 코드로 전달해야 합니다.

특정 지역에 편중된 결과

자동 완성 결과를 특정 지역으로 편중하려면 setLocationBias()를 호출하여 RectangularBounds를 전달합니다. 다음 코드 예에서는 프래그먼트 인스턴스에서 setLocationBias()를 호출하여 자동 완성 추천을 오스트레일리아 시드니 지역으로 편중하는 방법을 보여줍니다.

Kotlin



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

      

Java


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

      

검색 결과를 특정 지역으로 제한

자동 완성 결과를 특정 지역으로 제한하려면 setLocationRestriction()를 호출하여 RectangularBounds를 전달합니다. 다음 코드 예에서는 프래그먼트 인스턴스에서 setLocationRestriction()를 호출하여 자동 완성 추천을 오스트레일리아 시드니 지역으로 편중하는 방법을 보여줍니다.

Kotlin



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

      

Java


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

      

참고: 이 제한은 전체 경로에만 적용됩니다. 직사각형 경계 외부에 있는 합성 결과는 위치 제한과 겹치는 경로를 기반으로 반환될 수 있습니다.

장소 유형 또는 유형 모음으로 결과 필터링

특정 장소 유형만 반환하도록 자동 완성 요청의 결과를 제한할 수 있습니다. 장소 유형의 표 1, 2, 3에 나열된 장소 유형 또는 유형 모음을 사용하여 필터를 지정합니다. 아무것도 지정하지 않으면 모든 유형이 반환됩니다.

자동 완성 결과를 필터링하려면 setTypesFilter()를 호출하여 필터를 설정합니다.

유형 또는 유형 컬렉션 필터를 지정하려면 다음 안내를 따르세요.

  • setTypesFilter()를 호출하고 장소 유형의 표 1과 표 2에서 최대 5개의 type 값을 지정합니다. 유형 값은 PlaceTypes의 상수로 정의됩니다.

  • setTypesFilter()를 호출하고 장소 유형에 표시된 표 3에서 유형 컬렉션을 지정합니다. 컬렉션 값은 PlaceTypes의 상수로 정의됩니다.

    이 요청에서는 표 3의 단일 유형만 허용됩니다. 표 3의 값을 지정하는 경우 표 1이나 표 2의 값은 지정할 수 없습니다. 그러면 오류가 발생합니다.

다음 코드 예에서는 AutocompleteSupportFragment에서 setTypesFilter()를 호출하고 여러 유형 값을 지정합니다.

Kotlin



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

      

Java


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

      

다음 코드 예는 AutocompleteSupportFragment에서 setTypesFilter()를 호출하여 유형 컬렉션을 지정하여 정확한 주소가 있는 결과만 반환하는 필터를 설정하는 방법을 보여줍니다.

Kotlin



    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java


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

      

다음 코드 예에서는 IntentBuilder에서 setTypesFilter()를 호출하여 유형 컬렉션을 지정하여 정확한 주소가 있는 결과만 반환하는 필터를 설정하는 방법을 보여줍니다.

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()를 호출하여 국가 코드를 설정합니다. 그런 다음, 필터를 프래그먼트나 인텐트에 전달합니다. 국가는 2자리 ISO 3166-1 Alpha-2 호환 국가 코드로 전달해야 합니다.

다음 코드 예에서는 AutocompleteSupportFragment에서 setCountries()를 호출하여 지정된 국가 내의 결과만 반환하는 필터를 설정하는 방법을 보여줍니다.

Kotlin



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

      

Java


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

      

사용량 한도

Android용 Places SDK를 포함하여 Places API 사용이 더 이상 일일 최대 요청 수 (QPD)로 제한되지 않습니다. 하지만 다음 사용량 한도는 계속 적용됩니다.

  • 비율 제한은 6,000QPM (분당 요청 수)입니다. 동일한 프로젝트의 사용자 인증 정보를 사용하는 모든 애플리케이션에 대한 클라이언트 측 요청과 서버 측 요청의 합계로 계산됩니다.

앱에 특성 표시

  • 앱에서 프로그래매틱 방식으로 자동 완성 서비스를 사용하는 경우 UI가 'Google 제공' 저작자 표시를 표시하거나 Google 브랜드 지도 내에 표시해야 합니다.
  • 앱에서 자동 완성 위젯을 사용하는 경우 추가 작업이 필요하지 않습니다(필수 속성이 기본적으로 표시됨).
  • ID로 장소를 가져온 후에 추가 장소 정보를 가져와 표시하는 경우 서드 파티 저작자 표시도 표시해야 합니다.

자세한 내용은 기여 분석에 관한 문서를 참고하세요.

Place Autocomplete 최적화

이 섹션에서는 Place Autocomplete 서비스를 최대한 활용하는 데 도움이 되는 권장사항을 설명합니다.

다음은 일반 가이드라인입니다.

  • 작동하는 사용자 인터페이스를 개발하는 가장 빠른 방법은 Maps JavaScript API 자동 완성 위젯, Android용 Places SDK 자동 완성 위젯 또는 iOS용 Places SDK 자동 완성 UI 컨트롤을 사용하는 것입니다.
  • 기본적인 Place Autocomplete 데이터 필드를 처음부터 이해합니다.
  • 위치 상세 검색 및 위치 제한 필드는 선택사항이지만 자동 완성 성능에 상당한 영향을 미칠 수 있습니다.
  • API가 오류를 반환하는 경우 오류 처리를 사용하여 앱의 성능이 적절히 저하되도록 합니다.
  • 선택된 항목이 없을 때 앱에서 처리하고 사용자에게 계속할 수 있는 방법을 제공하도록 합니다.

비용 최적화 권장사항

기본 비용 최적화

Place Autocomplete 서비스 사용 비용을 최적화하려면 장소 세부정보 및 Place Autocomplete 위젯에서 필드 마스크를 사용하여 필요한 장소 데이터 필드만 반환하세요.

고급 비용 최적화

요청당 가격에 액세스하고 장소 세부정보 대신 선택된 장소에 대한 Geocoding API 결과를 요청하려면 Place Autocomplete를 프로그래매틱 방식으로 구현해 보세요. Geocoding API와 연결된 요청당 가격은 다음 두 조건이 모두 충족되는 경우 세션당(세션 기반) 가격보다 비용 효과적입니다.

  • 사용자가 선택한 장소의 위도/경도 또는 주소만 필요한 경우 Geocoding API는 장소 세부정보 호출보다 낮은 비용으로 이 정보를 제공합니다.
  • 사용자가 평균 네 개 이하의 자동 완성 예상 검색어 요청 내에서 자동 완성 예상 검색어를 선택하면 요청당 가격이 세션당 가격보다 비용 효과적일 수 있습니다.
요구에 맞는 Place Autocomplete 구현을 선택하는 데 도움이 필요하면 다음 질문에 대한 답변에 해당하는 탭을 선택하세요.

애플리케이션에 선택된 예상 검색어의 주소 및 위도/경도 이외의 정보가 필요한가요?

예, 추가 세부정보가 필요합니다.

세션 기반 Place Autocomplete를 장소 세부정보와 함께 사용
애플리케이션에 장소 이름, 비즈니스 상태 또는 영업시간 등의 장소 세부정보가 필요하므로 Place Autocomplete 구현 시 총 비용이 세션당 총 0.017달러인 세션 토큰(프로그래매틱 방식으로 또는 JavaScript ,Android 또는iOS에 내장하여) 및 요청하는 장소 데이터 필드에 따라 관련 장소 데이터 SKU를 사용해야 합니다.1

위젯 구현
세션 관리는 JavaScript, Android 또는 iOS에 자동으로 내장됩니다. 여기에는 선택된 예상 검색어에 대한 Place Autocomplete 요청 및 장소 세부정보 요청이 모두 포함됩니다. 필요한 장소 데이터 필드만 요청하도록 하려면 fields 매개변수를 지정해야 합니다.

프로그래매틱 구현
Place Autocomplete 요청에 세션 토큰을 사용합니다. 선택된 예상 검색어에 대해 장소 세부정보를 요청할 때 다음 매개변수를 포함합니다.

  1. Place Autocomplete 응답의 장소 ID
  2. Place Autocomplete 요청에 사용되는 세션 토큰
  3. 필요한 장소 데이터 필드를 지정하는 fields 매개변수

아니요, 주소와 위치만 필요합니다.

Place Autocomplete의 사용 성능에 따라 Geocoding API가 장소 세부정보보다 애플리케이션에 비용 효과적일 수 있습니다. 모든 애플리케이션의 자동 완성 효율성은 사용자가 입력하는 내용, 애플리케이션이 사용되는 위치, 성능 최적화 권장사항이 구현되었는지 여부에 따라 다릅니다.

다음 질문에 답변하려면 애플리케이션에서 Place Autocomplete 예상 검색어를 선택하기 전에 사용자가 평균적으로 입력하는 문자 수를 분석하세요.

사용자가 평균 네 개 이하의 요청에서 Place Autocomplete 예상 검색어를 선택하나요?

지원됨

세션 토큰 없이 프로그래매틱 방식으로 Place Autocomplete를 구현하고 선택한 장소 예상 검색어에 대해 Geocoding API 호출
Geocoding API는 주소 및 위도/경도 좌표를 요청당 0.005달러에 제공합니다. Place Autocomplete - Per Request를 4회 요청하는 데는 0.01132달러의 비용이 들기 때문에 선택된 장소 예상 검색어에 대한 4회 요청 및 Geocoding API 호출의 총 비용은 0.01632달러로 세션당 자동 완성 가격 0.017달러보다 작습니다.1

성능 권장사항을 사용하여 사용자가 훨씬 적은 수의 문자로 원하는 예상 검색어를 가져올 수 있도록 도와주세요.

아니요

세션 기반 Place Autocomplete를 장소 세부정보와 함께 사용
사용자가 Place Autocomplete 예상 검색어를 선택하기 전에 요청할 것으로 예상되는 평균 요청 수가 세션당 가격을 초과하므로 Place Autocomplete 구현 시 Place Autocomplete 요청 및 관련 장소 세부정보 요청 둘 다에 총 비용이 세션당 0.017달러인 세션 토큰을 사용해야 합니다.1

위젯 구현
세션 관리는 JavaScript, Android 또는 iOS에 자동으로 내장됩니다. 여기에는 선택된 예상 검색어에 대한 Place Autocomplete 요청 및 장소 세부정보 요청이 모두 포함됩니다. 기본 데이터 필드만 요청하도록 하려면 fields 매개변수를 지정해야 합니다.

프로그래매틱 구현
Place Autocomplete 요청에 세션 토큰을 사용합니다. 선택된 예상 검색어에 대해 장소 세부정보를 요청할 때 다음 매개변수를 포함합니다.

  1. Place Autocomplete 응답의 장소 ID
  2. Place Autocomplete 요청에 사용되는 세션 토큰
  3. 주소 및 도형과 같은 기본 데이터 필드를 지정하는 fields 매개변수

Place Autocomplete 요청 지연 고려
사용자가 처음 3~4자를 입력할 때까지 Place Autocomplete 요청을 지연하는 것과 같은 전략을 채택하여 애플리케이션에서 요청하는 횟수를 줄일 수 있습니다. 예를 들어 사용자가 세 번째 문자를 입력한 에 각 문자에 대해 Place Autocomplete 요청을 하면 사용자가 일곱 개의 문자를 입력한 다음 하나의 Geocoding API 요청을 한 예상 검색어를 선택하는 경우 총 비용이 0.01632달러(4*자동 완성 요청당 0.00283달러 + Geocoding 0.005달러)입니다.1

요청을 지연하면 평균 프로그래매틱 요청 수가 네 개 미만이 될 수 있는 경우 Geocoding API를 사용한 고성능 Place Autocomplete 구현을 위한 안내를 따르세요. 키를 입력할 때마다 예상 검색어가 표시될 것이라고 예상하는 사용자는 요청 지연을 지연 시간으로 인식할 수 있습니다.

성능 권장사항을 사용하여 사용자가 더 적은 수의 문자로 원하는 예상 검색어를 가져올 수 있도록 도와주세요.


  1. 여기에 표시된 비용은 미국 달러입니다. 전체 가격 정보는 Google Maps Platform 결제 페이지를 참고하세요.

성능 권장사항

다음 가이드라인에서는 Place Autocomplete 성능을 최적화하는 방법을 설명합니다.

  • Place Autocomplete 구현에 국가별 제한사항, 위치 상세 검색, (프로그래매틱 구현의 경우) 언어 환경설정을 추가합니다. 위젯은 사용자의 브라우저 또는 휴대기기에서 언어 환경설정을 선택하므로 언어 환경설정이 필요하지 않습니다.
  • Place Autocomplete에 지도와 함께 제공된 경우 지도 표시 영역별로 위치를 상세 검색할 수 있습니다.
  • 예상 검색어 중 원하는 결과 주소가 없어 사용자가 자동 완성 예상 검색어 중 하나를 선택하지 않는 경우 원래 사용자 입력을 재사용하여 더 관련성 높은 결과를 얻을 수 있습니다.
    • 사용자가 주소 정보만 입력할 것으로 예상되는 경우 Geocoding API 호출 시 원래 사용자 입력을 재사용합니다.
    • 사용자가 이름 또는 주소로 특정 장소에 대한 쿼리를 입력할 것으로 예상되는 경우 Find Place 요청을 사용합니다. 특정 지역에서만 결과가 예상되는 경우 위치 상세 검색을 사용합니다.
    다음과 같은 경우에는 Geocoding API로 대체하는 것이 가장 좋습니다.
    • 세부 주소의 Place Autocomplete 지원이 불완전한 국가(예: 체코, 에스토니아, 리투아니아)에서 사용자가 세부 주소를 입력하는 경우. 예를 들어 체코 주소인 'Stroupeсnického 3191/17, Praha'를 바탕으로 Place Autocomplete에서 부분 예측이 이루어집니다.
    • 사용자가 뉴욕시의 '23-30 29th St, Queens' 또는 하와이 카우아이섬의 '47-380 Kamehameha Hwy, Kaneohe'처럼 도로 구간 접두사가 있는 주소를 입력하는 경우

문제 해결

다양한 오류가 발생할 수 있지만 일반적으로 앱에서 발생할 수 있는 대부분의 오류는 구성 오류 (예: 잘못된 API 키가 사용되었거나 API 키가 잘못 구성됨) 또는 할당량 오류 (앱이 할당량을 초과함)로 인해 발생합니다. 할당량에 대한 자세한 내용은 사용량 한도를 참조하세요.

자동 완성 컨트롤 사용 시 발생하는 오류는 onActivityResult() 콜백에 반환됩니다. 결과의 상태 메시지를 가져오려면 Autocomplete.getStatus()를 호출합니다.