자동 완성 (신규)

Autocomplete (신규)는 텍스트 검색 문자열과 검색 영역을 제어하는 지리적 경계를 포함하는 요청에 대한 응답으로 장소 예측을 반환합니다. 자동 완성은 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소 및 Plus Code를 결정할 수 있습니다. 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 및 쿼리 예상 검색어를 제공할 수 있습니다.

예를 들어 검색 영역이 캘리포니아주 샌프란시스코로 제한된 상태에서 부분 사용자 입력 'Sicilian piz'가 포함된 문자열을 입력으로 사용하여 Autocomplete를 호출합니다. 그러면 응답에 검색 문자열 및 검색 지역과 일치하는 장소 예측 목록(예: 'Sicilian Pizza Kitchen'이라는 레스토랑)이 포함됩니다. 반환된 장소 예측은 사용자가 원하는 장소를 선택하는 데 도움이 되도록 사용자에게 표시되도록 설계되었습니다. 장소 세부정보(신규) 요청을 통해 반환된 장소 예측에 대한 자세한 정보를 확인할 수 있습니다.

다음 두 가지 주요 방법으로 Autocomplete (New) 기능을 앱에 통합할 수 있습니다.

• Place Autocomplete 위젯 추가: 사용자가 입력할 때 예측을 표시하는 PlaceAutocomplete 클래스를 통해 바로 사용할 수 있는 검색 자동 완성 환경을 제공합니다.
• 프로그래매틱 방식으로 장소 예측 가져오기: API를 직접 호출하여 예측을 가져오고 맞춤 사용자 인터페이스에 표시합니다.

Place Autocomplete 위젯 추가

일관된 장소 자동 완성 환경을 더 쉽게 제공하려면 앱에 Place Autocomplete 위젯을 추가하면 됩니다. 이 위젯은 사용자 입력을 처리하고 사용자에게 장소 예측을 표시하는 전용 전체 화면 인터페이스를 제공하는 동시에 앱에 AutocompletePrediction 객체를 반환합니다. 그런 다음 장소 세부정보(신규) 요청을 통해 장소 예측에 관한 추가 정보를 가져올 수 있습니다.

프로그래매틱 방식으로 장소 예상 검색어를 가져오는 경우와 마찬가지로 Place Autocomplete 위젯을 사용하면 세션 토큰을 사용하여 결제 목적으로 자동 완성 요청을 세션으로 그룹화할 수 있습니다. setAutocompleteSessionToken()를 호출하여 위젯의 인텐트를 만들 때 세션 토큰을 전달할 수 있습니다. 세션 토큰을 제공하지 않으면 위젯에서 세션 토큰을 생성하며, getSessionTokenFromIntent()를 호출하여 액세스할 수 있습니다. 세션 토큰 사용에 관한 자세한 내용은 세션 토큰 정보를 참고하세요.

앱에 Place Autocomplete 위젯을 추가하려면 다음 단계를 따르세요.

1. (선택사항) 세션 토큰을 정의합니다. 세션 토큰을 제공하지 않으면 위젯에서 세션 토큰을 생성합니다.

2. 원하는 매개변수와 세션 토큰을 사용하여 autocompleteIntent를 정의합니다.

3. StartActivityForResult의 ActivityResultLauncher을 정의합니다. 이 런처는 자동 완성 활동에서 반환된 결과를 처리합니다.

4. ActivityResultLauncher 콜백에서 결과를 처리합니다. 여기에는 AutocompletePrediction 및 AutocompleteSessionToken 추출 (직접 제공하지 않은 경우), 오류 처리, 선택적으로 fetchPlace() 요청을 통해 장소에 관한 추가 세부정보 가져오기가 포함됩니다.

5. placeAutocompleteActivityResultLauncher를 사용하여 인텐트 실행

다음 샘플은 Kotlin과 Java를 모두 사용하여 Place Autocomplete 위젯을 추가하는 방법을 보여줍니다.

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

테마 맞춤설정

Autocomplete 환경을 인스턴스화할 때 기본 스타일 속성을 재정의하는 테마를 지정할 수 있습니다. Place Autocomplete 구성요소의 색상, 서체, 간격, 테두리, 모서리를 맞춤설정할 수 있습니다. 기본값은 PlacesMaterialTheme입니다. 재정의되지 않은 테마 속성은 기본 스타일을 사용합니다.

…/res/values/themes.xml에서 테마 재정의를 정의할 수 있습니다. 예를 들면 다음과 같습니다.

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

그런 다음 setAutocompleteUiCustomization를 호출하여 재정의 스타일을 참조할 수 있습니다.

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

프로그래매틱 방식으로 장소 예측 가져오기

앱은 PlacesClient.findAutocompletePredictions()를 호출하고 FindAutocompletePredictionsRequest 객체를 전달하여 자동 완성 API에서 예측된 장소 이름 또는 주소 목록을 가져올 수 있습니다. 아래 예는 PlacesClient.findAutocompletePredictions()에 대한 전체 호출을 보여줍니다.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete (신규) 응답

API는 Task에서 FindAutocompletePredictionsResponse을 반환합니다. FindAutocompletePredictionsResponse에는 예측된 장소를 나타내는 최대 5개의 AutocompletePrediction 객체 목록이 포함됩니다. 쿼리 및 필터 기준에 해당하는 알려진 장소가 없으면 목록이 비어 있을 수 있습니다.

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

• getFullText(CharacterStyle)은 장소 설명의 전체 텍스트를 반환합니다. 기본 텍스트와 보조 텍스트의 조합입니다. 예: '에펠탑, 아나톨 프랑스 거리, 파리, 프랑스' 또한 이 메서드를 사용하면 CharacterStyle을 사용하여 검색과 일치하는 설명 섹션을 원하는 스타일로 강조 표시할 수 있습니다. CharacterStyle 파라미터는 선택사항입니다. 강조 표시가 필요하지 않으면 null로 설정합니다.
• getPrimaryText(CharacterStyle)은 장소를 설명하는 기본 텍스트를 반환합니다. 일반적으로 장소의 이름입니다. 예: '에펠탑', '피트 스트리트 123번지'
• getSecondaryText(CharacterStyle)은 장소 설명의 보조 텍스트를 반환합니다. 이는 자동 완성 예측을 표시할 때 두 번째 줄로 유용합니다. 예: 'Avenue Anatole France, Paris, France', 'Sydney, New South Wales'
• getPlaceId()은 예측된 장소의 장소 ID를 반환합니다. 장소 ID는 장소를 고유하게 나타내는 텍스트 식별자이며, 이를 사용하여 나중에 Place 객체를 다시 가져올 수 있습니다. Autocomplete의 장소 ID에 대한 자세한 내용은 장소 세부정보(신규)를 참고하세요. 장소 ID에 대한 일반 정보는 장소 ID 개요를 참고하세요.
• getTypes()는 이 장소와 연결된 장소 유형 목록을 반환합니다.
• getDistanceMeters()은 이 장소와 요청에 지정된 원점 사이의 직선 거리를 미터 단위로 반환합니다.

필수 매개변수

• 쿼리

  검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, Plus Code를 지정합니다. Autocomplete (New) 서비스는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.

  쿼리 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setQuery() 메서드를 호출합니다.

선택적 매개변수

• 기본 유형

  응답에서 반환된 장소를 필터링하는 데 사용되는 유형 표 A 또는 표 B의 최대 5개 유형 값 목록입니다. 장소가 응답에 포함되려면 지정된 기본 유형 값 중 하나와 일치해야 합니다.

  장소에는 표 A 또는 표 B 유형 중 하나만 연결될 수 있습니다. 예를 들어 기본 유형은 "mexican_restaurant" 또는 "steak_house"일 수 있습니다.

  다음과 같은 경우 요청이 INVALID_REQUEST 오류와 함께 거부됩니다.

  • 6개 이상의 유형이 지정되었습니다.
  • 인식할 수 없는 유형이 지정됩니다.

  기본 유형 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setTypesFilter() 메서드를 호출합니다.

• 국가

  최대 15개의 ccTLD ('최상위 도메인') 2자리 값 목록으로 지정된 지정된 국가 목록의 결과만 포함합니다. 생략하면 응답에 제한이 적용되지 않습니다. 예를 들어 지역을 독일과 프랑스로 제한하려면 다음을 실행합니다.

  locationRestriction와 includedRegionCodes을 모두 지정하면 결과가 두 설정의 교차 영역에 위치합니다.

  국가 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setCountries() 메서드를 호출합니다.

• 입력 오프셋

  쿼리에서 커서 위치를 나타내는 0부터 시작하는 유니코드 문자 오프셋입니다. 커서 위치는 반환되는 예측에 영향을 줄 수 있습니다. 비어 있으면 기본값은 쿼리 길이입니다.

  입력 오프셋 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setInputOffset() 메서드를 호출합니다.

• 위치 편향 또는 위치 제한

  위치 편향 또는 위치 제한을 지정하여 검색 영역을 정의할 수 있습니다. 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 있어야 하는 지역을 지정하는 것으로, 위치 편향은 결과가 있어야 하는 지역을 지정하는 것으로 생각하면 됩니다. 주요 차이점은 위치 편향을 사용하면 지정된 지역 외부의 결과가 반환될 수 있다는 것입니다.

  • 위치 편향

    검색할 영역을 지정합니다. 이 위치는 제한이 아닌 편향으로 작용하므로 지정된 영역 밖의 결과가 반환될 수도 있습니다.

    위치 편향 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setLocationBias() 메서드를 호출합니다.

  • 위치 제한

    검색할 영역을 지정합니다. 지정된 영역 외부의 결과는 반환되지 않습니다.

    위치 제한 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setLocationRestriction() 메서드를 호출합니다.

  위치 편향 또는 위치 제한 영역을 직사각형 Viewport 또는 원으로 지정합니다.

  • 원은 중심점과 반지름(미터)으로 정의됩니다. 반지름은 0.0 이상 50000.0 이하여야 합니다. 기본값은 0.0입니다. 위치 제한의 경우 반경을 0.0보다 큰 값으로 설정해야 합니다. 그렇지 않으면 요청에서 결과를 반환하지 않습니다.

  • 직사각형은 대각선으로 반대되는 두 개의 low 및 high 포인트로 표현되는 위도-경도 표시 영역입니다. 표시 영역은 경계를 포함하는 닫힌 영역으로 간주됩니다. 위도 범위는 -90~90도(포함)여야 하고 경도 범위는 -180~180도(포함)여야 합니다.

    • low = high이면 표시 영역은 해당 단일 점으로 구성됩니다.
    • low.longitude > high.longitude인 경우 경도 범위가 반전됩니다(표시 영역이 180도 경도선을 교차함).
    • low.longitude = -180도이고 high.longitude = 180도인 경우 뷰포트에는 모든 경도가 포함됩니다.
    • low.longitude = 180도이고 high.longitude = -180도인 경우 경도 범위가 비어 있습니다.

    low와 high가 모두 채워져야 하며, 표현된 상자는 비워 둘 수 없습니다. 뷰포트가 비어 있으면 오류가 발생합니다.

• 출발지

  목적지까지의 직선 거리를 계산할 원점입니다 (getDistanceMeters()를 사용하여 액세스). 이 값이 생략되면 직선 거리가 반환되지 않습니다. 위도 및 경도 좌표로 지정해야 합니다.

  출처 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setOrigin() 메서드를 호출합니다.

• 지역 코드

  주소 형식을 포함하여 응답 형식을 지정하는 데 사용되는 지역 코드입니다. ccTLD ('최상위 도메인') 2자리 값으로 지정됩니다. 대부분의 ccTLD 코드는 ISO 3166-1 코드와 동일하지만 일부 주목할 만한 예외가 있습니다. 예를 들어 영국의 ccTLD는 'uk' (.co.uk)이지만 ISO 3166-1 코드는 'gb' (기술적으로 '영국' 법인의 경우)입니다.

  잘못된 지역 코드를 지정하면 API에서 INVALID_ARGUMENT 오류를 반환합니다. 이 매개변수는 관련 법규에 따라 결과에 영향을 미칠 수 있습니다.

  지역 코드 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setRegionCode() 메서드를 호출합니다.

• 세션 토큰

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

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

  세션 토큰 매개변수를 설정하려면 FindAutocompletePredictionsRequest 객체를 빌드할 때 setSessionToken() 메서드를 호출합니다.

  자세한 내용은 세션 토큰을 참고하세요.

Autocomplete (신규) 예시

위치 제한 및 위치 편향 사용

자동 완성 (신규)은 기본적으로 IP 바이어스를 사용하여 검색 영역을 제어합니다. IP 바이어싱을 사용하면 API가 기기의 IP 주소를 사용하여 결과를 바이어스합니다. 선택적으로 위치 제한 또는 위치 편향을 사용하여 검색할 지역을 지정할 수 있습니다. 둘 다 사용할 수는 없습니다.

위치 제한은 검색할 영역을 지정합니다. 지정된 영역 밖의 결과는 반환되지 않습니다. 다음 예에서는 위치 제한을 사용하여 요청을 샌프란시스코를 중심으로 하는 반경 5,000미터의 원형 위치 제한으로 제한합니다.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

위치 편향을 사용하면 위치가 편향으로 작용하므로 지정된 지역 외부의 결과를 포함하여 지정된 위치 주변의 결과가 반환될 수 있습니다. 다음 예에서는 위치 편향을 사용하도록 이전 요청을 변경합니다.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

기본 유형 사용

기본 유형 매개변수를 사용하여 요청의 결과를 표 A 및 표 B에 나열된 특정 유형으로 제한합니다. 최대 5개의 값으로 구성된 배열을 지정할 수 있습니다. 생략하면 모든 유형이 반환됩니다.

다음 예에서는 쿼리 문자열로 'Soccer'를 지정하고 기본 유형 매개변수를 사용하여 결과를 "sporting_goods_store" 유형의 시설로 제한합니다.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

기본 유형 매개변수를 생략하면 "athletic_field"와 같이 원치 않는 유형의 시설이 결과에 포함될 수 있습니다.

원본 사용

요청에 origin 매개변수를 위도 및 경도 좌표로 지정하여 포함하면 API는 원점에서 목적지까지의 직선 거리를 응답에 포함합니다 (getDistanceMeters()를 사용하여 액세스). 다음 예에서는 원점을 샌프란시스코의 중심으로 설정합니다.

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete (신규) 최적화

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

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

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

비용 최적화 권장사항

기본 비용 최적화

Autocomplete (New) 서비스 사용 비용을 최적화하려면 Place Details (New) 및 Autocomplete (New) 위젯에서 필드 마스크를 사용하여 필요한 Autocomplete (New) 데이터 필드만 반환하세요.

고급 비용 최적화

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

• 사용자가 선택한 장소의 위도/경도 또는 주소만 필요한 경우 Geocoding API는 장소 세부정보 (신규) 호출보다 낮은 비용으로 이 정보를 제공합니다.
• 사용자가 평균 네 개 이하의 자동 완성 (신규) 예상 검색어 요청 내에서 자동 완성 예상 검색어를 선택하면 요청당 가격이 세션당 가격보다 비용 효과적일 수 있습니다.

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

성능 권장사항

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

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

위치 편향

location 매개변수와 radius 매개변수를 전달하여 지정된 지역에 편중된 결과를 얻을 수 있습니다. 이렇게 하면 자동 완성 (신규)이 정의된 영역 내의 결과를 표시하도록 선호합니다. 정의된 영역 밖의 결과가 표시될 수도 있습니다. components 매개변수를 사용하여 결과를 필터링하여 지정된 국가 내의 장소만 표시할 수 있습니다.

위치 제한

locationRestriction 매개변수를 전달하여 결과를 지정된 영역으로 제한합니다.

location 및 radius 매개변수로 정의된 지역으로 결과를 제한하려면 locationRestriction 매개변수를 추가하세요. 이렇게 하면 자동 완성 (신규)이 해당 지역 내의 결과만 반환하도록 지시합니다.