Autocomplete (신규)는 텍스트 검색 문자열과 검색 영역을 제어하는 지리적 경계를 포함하는 요청에 대한 응답으로 장소 예상 검색어를 반환합니다. 자동 완성은 입력의 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소 및 Plus Code를 결정할 수 있습니다. 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 및 예상 검색어를 제공할 수 있습니다.
예를 들어 캘리포니아 샌프란시스코로 제한된 검색 영역이 포함된 'Sicilian piz'라는 부분 사용자 입력이 포함된 문자열을 입력으로 사용하여 Autocomplete를 호출합니다. 응답에는 'Sicilian Pizza Kitchen'이라는 이름의 식당 등 검색 문자열 및 검색 영역과 일치하는 장소 예상 검색어 목록이 포함됩니다.
반환된 장소 예상 검색어는 사용자에게 표시되어 원하는 장소를 선택하는 데 도움을 줄 수 있습니다. 장소 세부정보(신규) 요청을 통해 반환된 장소 예상 검색어에 대한 자세한 정보를 가져올 수 있습니다.
자동 완성 (신규) 요청
앱은 PlacesClient.findAutocompletePredictions()를 호출하고 FindAutocompletePredictionsRequest 객체를 전달하여 Autocomplete 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());
})
);
자동 완성 (신규) 응답
이 API는 Task에 FindAutocompletePredictionsResponse를 반환합니다.
FindAutocompletePredictionsResponse에는 예상 장소를 나타내는 최대 5개의 AutocompletePrediction 객체 목록이 포함됩니다. 쿼리 및 필터 기준에 해당하는 알려진 장소가 없으면 목록이 비어 있을 수 있습니다.
각 예상 장소에 대해 다음 메서드를 호출하여 장소 세부정보를 가져올 수 있습니다.
getFullText(CharacterStyle)는 장소 설명의 전체 텍스트를 반환합니다. 이 텍스트는 기본 텍스트와 보조 텍스트가 조합되어 있습니다. 예: 'Eiffel Tower, Avenue Anatole France, Paris, 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객체를 다시 검색하는 데 사용할 수 있습니다. Autocomplete의 장소 ID에 관한 자세한 내용은 장소 세부정보(신규)를 참고하세요. 장소 ID에 대한 일반적인 정보는 장소 ID 개요를 참고하세요.getTypes()는 이 장소와 연결된 장소 유형 목록을 반환합니다.getDistanceMeters()은 이 장소와 요청에 지정된 출발지 사이의 직선 거리(미터)를 반환합니다.
필수 매개변수
-
쿼리
검색할 텍스트 문자열입니다. 전체 단어 및 하위 문자열, 장소 이름, 주소, 플러스 코드를 지정합니다. Autocomplete (신규) 서비스는 이 문자열을 기준으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기준으로 검색 결과의 순서를 지정합니다.
쿼리 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setQuery()메서드를 호출합니다.
선택적 매개변수
-
기본 유형
응답에서 반환된 장소를 필터링하는 데 사용되는 테이블 A 또는 테이블 B 유형의 유형 값 최대 5개 목록 장소는 응답에 포함할 지정된 기본 유형 값 중 하나와 일치해야 합니다.
장소에는 연결된 테이블 A 또는 테이블 B 유형의 단일 기본 유형만 있을 수 있습니다. 예를 들어 기본 유형은
"mexican_restaurant"또는"steak_house"일 수 있습니다.다음과 같은 경우
INVALID_REQUEST오류와 함께 요청이 거부됩니다.- 5개 이상의 유형이 지정되었습니다.
- 인식할 수 없는 유형이 모두 지정되었습니다.
기본 유형 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setTypesFilter()메서드를 호출합니다. -
국가
최대 15개의 ccTLD ('최상위 도메인') 2자 값 목록으로 지정된 지정된 국가 목록의 결과만 포함합니다. 생략할 경우 응답에 제한이 적용되지 않습니다. 예를 들어 리전을 독일과 프랑스로 제한하는 방법은 다음과 같습니다.
locationRestriction과includedRegionCodes를 모두 지정하면 두 설정이 교차하는 영역에 결과가 표시됩니다.국가 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setCountries()메서드를 호출합니다. -
입력 오프셋
쿼리에서 커서 위치를 나타내는 0 기준 유니코드 문자 오프셋입니다. 커서 위치는 반환되는 예상 검색어에 영향을 줄 수 있습니다. 비어 있으면 기본적으로 쿼리 길이로 설정됩니다.
입력 오프셋 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setInputOffset()메서드를 호출합니다. 특정 위치 편중 또는 위치 제한
검색 지역을 정의하기 위해 위치 상세 검색 또는 위치 제한을 지정할 수 있지만 둘 다 지정할 수는 없습니다. 위치 제한은 결과가 포함되어야 하는 지역을 지정하는 것으로, 위치 편향은 결과가 있어야 하는 지역을 지정하는 것으로 생각하세요. 주요 차이점은 위치 편향의 경우 지정된 지역을 벗어난 결과가 여전히 반환될 수 있다는 것입니다.
위치 상세 검색
검색할 영역을 지정합니다. 이 위치는 제한이 아닌 편향으로 기능하므로 지정된 영역을 벗어난 결과가 여전히 반환될 수 있습니다.
위치 상세 검색 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setLocationBias()메서드를 호출합니다.위치 제한
검색할 영역을 지정합니다. 지정된 영역을 벗어난 결과는 반환되지 않습니다.
위치 제한 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setLocationRestriction()메서드를 호출합니다.
위치 상세 검색 또는 위치 제한 지역을 직사각형 표시 영역 또는 원으로 지정합니다.
원은 중심점과 반지름(미터)으로 정의됩니다. 반경은 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()메서드를 호출합니다. -
세션 토큰
세션 토큰은 자동 완성 (신규) 호출을 '세션'으로 추적하는 사용자 생성 문자열입니다. Autocomplete는 세션 토큰을 사용하여 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션은 사용자가 쿼리를 입력하기 시작하면 시작되고 장소를 선택하면 종료됩니다. 세션마다 여러 개의 쿼리가 포함될 수 있으며 하나의 장소가 선택됩니다. 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱은 각 세션에 대해 새 토큰을 생성해야 합니다. 모든 프로그래매틱 자동 완성 세션에 세션 토큰을 사용하는 것이 좋습니다. 프래그먼트를 삽입하거나 인텐트를 사용하여 자동 완성을 실행하면 API가 이 작업을 자동으로 처리합니다.
자동 완성은
AutocompleteSessionToken를 사용하여 각 세션을 식별합니다. 앱은 새로운 각 세션을 시작할 때 새 세션 토큰을 전달하고 이후fetchPlace()호출에서 장소 ID와 함께 동일한 토큰을 전달하여 사용자가 선택한 장소의 장소 세부정보를 가져와야 합니다.세션 토큰 매개변수를 설정하려면
FindAutocompletePredictionsRequest객체를 빌드할 때setSessionToken()메서드를 호출합니다.자세한 내용은 세션 토큰을 참조하세요.
자동 완성 (신규) 예시
위치 제한 및 위치 상세 검색 사용
자동 완성 (신규)은 기본적으로 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개 값의 배열을 지정할 수 있습니다. 생략하면 모든 유형이 반환됩니다.
다음 예에서는 'Socer' 쿼리 문자열을 지정하고 기본 유형 매개변수를 사용하여 결과를 "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());
})
);
기여 분석
지도 없이도 자동 완성 (신규)을 사용할 수 있습니다. 지도를 표시하는 경우에는 반드시 Google 지도를 표시해야 합니다. 자동 완성 (신규) 서비스에서 지도 없이 예상 검색어를 표시하는 경우 검색창/결과와 나란히 표시된 Google 로고를 포함해야 합니다. 자세한 내용은 Google 로고 및 저작자 표시를 참고하세요.