모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Places API for Android 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Places API for Android 활성화
  3. 적합한 키 생성
계속

장소 자동완성

Google Places API for Android의 자동완성 서비스는 사용자 검색 쿼리에 대한 응답으로 장소 예상 검색어를 반환합니다. 자동완성 서비스는 사용자가 입력하는 중에 사업체, 주소, 관심 지점 등의 제안을 반환합니다.

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

자동완성 위젯 추가

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

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

옵션 1: PlaceAutocompleteFragment 또는 SupportPlaceAutocompleteFragment를 삽입

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

  1. 프래그먼트를 액티비티의 XML 레이아웃에 추가합니다.
  2. 리스너를 액티비티나 프래그먼트에 추가합니다.

PlaceAutocompleteFragment를 액티비티에 추가

PlaceAutocompleteFragment를 액티비티에 추가하려면, 이름이 com.google.android.gms.location.places.ui.PlaceAutocompleteFragment인 새 프래그먼트를 XML 레이아웃에 추가합니다. 예:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

참고: 기본적으로, 프래그먼트에는 테두리나 배경이 없습니다. 일관된 시각적 모양을 제공하려면, 다음과 같은 또 다른 레이아웃 요소 내에 프래그먼트를 중첩시킵니다: CardView.

PlaceSelectionListener를 액티비티에 추가

PlaceSelectionListener는 사용자의 선택에 반응하여 장소를 반환하는 작업을 처리합니다. 다음 코드는 프래그먼트에 대한 참조를 만들고 리스너를 PlaceAutocompleteFragment에 추가하는 방법을 보여줍니다.

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
    @Override
    public void onPlaceSelected(Place place) {
        // TODO: Get info about the selected place.
        Log.i(TAG, "Place: " + place.getName());
    }

    @Override
    public void onError(Status status) {
        // TODO: Handle the error.
        Log.i(TAG, "An error occurred: " + status);
    }
  });

SupportPlaceAutocompleteFragment 사용(구형 플랫폼)

Google Places API가 PlaceAutocompleteFragment 객체를 지원하려면 API 레벨 12 이상이 필요합니다. API 레벨 12 이전의 애플리케이션을 대상으로 하는 경우, SupportPlaceAutocompleteFragment 클래스를 통해 동일 기능에 액세스할 수 있습니다. Android v4 지원 라이브러리도 포함해야 합니다. API 레벨 12 이전의 Android 버전을 지원하려면 다음 단계를 따릅니다.

  • 기본 액티비티에서 FragmentActivity 또는 AppCompatActivity를 확장합니다.
  • PlaceAutocompleteFragment 대신 SupportPlaceAutocompleteFragment를 사용합니다.
  • getFragmentManager() 대신 getSupportFragmentManager()를 사용합니다.

옵션 2: 인텐트를 사용하여 자동완성 액티비티를 실행합니다.

앱에서 다른 탐색 흐름을 사용하려는 경우(예: 검색 필드 대신 아이콘에서 자동완성 환경을 트리거), 앱이 인텐트를 사용하여 자동완성을 실행할 수 있습니다.

참고: 프래그먼트를 삽입하는 경우 이러한 단계가 필요 없습니다.

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

  1. PlaceAutocomplete.IntentBuilder을 사용하여 인텐트를 만들고, 원하는 PlaceAutocomplete 모드를 전달합니다. 인텐트는 startActivityForResult를 호출해야 하며, 이 인텐트를 식별하는 요청 코드를 전달해야 합니다.
  2. 선택한 장소를 수신하도록 onActivityResult 콜백을 재정의합니다.

자동완성 인텐트 만들기

아래 예시에서는 PlaceAutocomplete.IntentBuilder를 사용하여 인텐트를 만들고, 자동완성 위젯을 인텐트로 실행하는 방법을 보여줍니다.

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO: Handle the error.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO: Handle the error.
}

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

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
그림 1: 오버레이 모드의 자동완성 위젯 (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
그림 2: 전체 화면 모드의 자동완성 위젯 (MODE_FULLSCREEN)

onActivityResult 콜백 재정의

사용자가 장소를 선택했을 때 여러분의 앱이 알림을 수신하려면, 앱에서 액티비티의 onActivityResult()를 재정의하고, 인텐트에 대해 전달한 요청 코드를 확인해야 합니다(다음 예시 참조).

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO: Handle the error.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled operation.
        }
    }
}

자동완성 결과 제한

특정 지리적 지역으로 결과가 편중되도록 자동완성 위젯을 설정할 수 있고, 하나 이상의 장소 유형에 따라 결과를 필터링할 수 있습니다.

특정 지역으로 결과 편중

특정 지리적 지역으로 자동완성 결과를 편중하려면:

  • 앱의 PlaceAutocompleteFragment 인스턴스 또는 IntentBuilder 인스턴스에서 setBoundsBias()를 호출하고, LatLngBounds를 전달합니다. 다음 코드 예시에서는 프래그먼트 인스턴스에서 setBoundsBias()를 호출하여 자동완성 제안을 호주 시드니 지역으로 편중하는 방법을 보여줍니다.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

장소 유형별로 결과 필터링

특정 장소 유형에 따라 자동완성 결과를 필터링하려면, AutocompleteFilter.Builder를 호출하여 새 AutocompleteFilter을 만들고, setTypeFilter()을 호출하여 사용할 필터를 설정합니다. 그런 다음, 필터를 프래그먼트나 인텐트에 전달합니다.

다음 코드 예시에서는 PlaceAutocompleteFragmentAutocompleteFilter를 설정하여 정밀 주소가 있는 결과만을 반환하는 필터를 설정합니다.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

다음 코드 예시에서는 인텐트에 AutocompleteFilter를 설정하여 정밀 주소가 있는 결과만을 반환하는 필터를 설정합니다.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

장소 유형에 대한 자세한 내용은 장소 유형AutocompleteFilter.Builder 가이드를 참조하세요.

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

자동완성 위젯에 의해 제공되는 UI의 대안으로 사용자 지정 검색 UI를 만들 수 있습니다. 이를 위해서는 장소 예상 검색어를 프로그래밍 방식으로 가져와야 합니다. GeoDataApi.getAutocompletePredictions()를 호출하고 다음 매개변수를 전달하여, 앱이 예상 장소 이름 및/또는 주소 목록을 자동완성 서비스로부터 가져올 수 있습니다.

  • 필수: 사용자가 입력한 텍스트를 포함하는 query 문자열.
  • 필수: 위도 및 경도 경계로 지정된 특정 영역으로 결과를 편중하는 LatLngBounds 객체.
  • 선택 항목: 장소 유형 집합을 포함하는 AutocompleteFilter를 사용하여 하나 이상의 장소 유형으로 결과를 제한할 수 있습니다. 지원되는 장소 유형:

    • TYPE_FILTER_NONE – 빈 필터로, 모든 결과가 반환됩니다.
    • TYPE_FILTER_GEOCODE– 사업체 대신 지오코딩 결과만 반환합니다. 지정된 위치가 명확하지 않은 경우 이 요청을 사용하여 결과를 명확히 나타낼 수 있습니다.
    • TYPE_FILTER_ADDRESS– 정확한 주소를 지닌 자동완성 결과만 반환합니다. 사용자가 전체 주소를 찾고 있다는 것을 알고 있다면 이 유형을 사용하세요.
    • TYPE_FILTER_ESTABLISHMENT– 사업체인 장소만 반환합니다.
    • TYPE_FILTER_REGIONS – 다음 유형 중 하나와 일치하는 장소만 반환합니다.

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIESlocality 또는 administrative_area_level_3과 일치하는 결과만 반환합니다.

장소 유형에 대한 자세한 내용은 장소 유형AutocompleteFilter.Builder 가이드를 참조하세요.

아래의 예시는 간단한 GeoDataApi.getAutocompletePredictions() 호출을 보여줍니다. 전체 예시는 샘플 앱을 참조하세요.

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

이 API는 AutocompletePredictionBuffer PendingResult에 반환합니다. AutocompletePredictionBuffer에는 예상 장소를 나타내는 AutocompletePrediction 객체의 목록이 포함됩니다. 쿼리와 필터 기준에 해당하는 알려진 장소가 없으면 버퍼가 비어있을 수 있습니다.

참고: 메모리 누수를 방지하려면, 앱에서 더 이상 필요하지 않은 AutocompletePredictionBuffer 객체를 해제해야 합니다. 버퍼 처리에 대해 자세히 알아보세요.

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

  • getFullText(CharacterStyle matchStyle)는 장소 설명의 전체 텍스트를 반환합니다. 이 텍스트는 기본 텍스트와 보조 텍스트가 조합된 것입니다. 예: "Eiffel Tower, Avenue Anatole France, Paris, France". 또한 이 메서드에서는 사용자가 선택한 스타일과 검색 결과가 일치하는 설명 부분을 강조 표시할 수 있으며, 이를 위해 CharacterStyle.를 사용합니다. CharacterStyle 매개변수는 선택 항목입니다. 강조 표시가 필요없는 경우는 이 매개변수를 null로 설정하세요.
  • getPrimaryText(CharacterStyle matchStyle)는 장소를 설명하는 기본 텍스트를 반환합니다. 일반적으로 장소 이름입니다. 예: "Eiffel Tower" 및 "123 Pitt Street".
  • getSecondaryText(CharacterStyle matchStyle)는 장소 설명의 보조 텍스트를 반환합니다. 이 텍스트는 예를 들어, 자동완성 예상 검색어를 표시할 때 두 번째 줄로 유용합니다. 예: "Avenue Anatole France, Paris, France" 및 "Sydney, New South Wales".
  • getPlaceId()는 예상 장소의 장소 ID를 반환합니다. 장소 ID는 장소를 고유하게 식별하는 텍스트 식별자이며, 이것을 사용하여 Place 객체를 나중에 다시 검색할 수 있습니다. Google Places API for Android에서 장소 ID에 대한 자세한 내용은 장소 ID 및 세부정보를 참조하세요. 장소 ID에 대한 일반적인 내용은 장소 ID 개요를 참조하세요.
  • [getPlaceTypes()](/android/reference/com/google/android/gms/location/places/AutocompletePrediction.html#getPlaceTypes()는 이 장소와 연관된 장소 유형 목록을 반환합니다.

사용 제한

앱에 특성 표시

  • 앱이 프로그래밍 방식으로 자동완성 서비스를 사용하는 경우, UI가 'Powered by Google' 속성을 표시하거나 Google 브랜드 지도 내에 나타나야 합니다.
  • 앱이 자동완성 위젯을 사용하는 경우에는 추가적인 동작이 필요 없습니다(필수 속성은 기본적으로 표시됩니다).
  • ID로 장소를 획득한 후에 추가 장소 정보를 검색하고 표시하는 경우, 타사 특성도 표시해야 합니다.

자세한 내용은 특성에 대한 문서를 참조하세요.

문제 해결

광범위한 오류가 발생할 수 있지만, 일반적으로 앱에 발생하는 오류의 대다수는 구성 오류이거나(예: 잘못된 API 키가 사용되거나 API 키가 잘못 구성됨) 할당량 오류입니다(앱이 할당량을 초과함). 할당량에 대한 자세한 내용은 사용 제한을 참조하세요.

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

다음에 대한 의견 보내기...

location_on
Google Places API for Android