Place Autocomplete

소개

자동 완성은 Maps JavaScript API에 포함되어 있는 장소 라이브러리의 기능입니다. 자동 완성을 사용하여 애플리케이션에 Google 지도 검색창의 검색 전 입력 기능을 제공할 수 있습니다. 자동 완성 서비스는 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소 및 Plus Code를 결정할 수 있습니다. 따라서 사용자가 입력함에 따라 애플리케이션에서 쿼리를 전송하여 즉시 장소 예상 검색어를 제공할 수 있습니다.

시작하기

Maps JavaScript API에서 장소 라이브러리를 사용하려면 먼저 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트의 Google Cloud 콘솔에서 Places API를 사용 설정해야 합니다.

사용 설정된 API의 목록을 보려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔로 이동합니다.
  2. 프로젝트 선택 버튼을 클릭한 후 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트를 선택하고 열기를 클릭합니다.
  3. 대시보드의 API 목록에서 Places API를 찾습니다.
  4. 목록에 API가 표시되면 완료된 것입니다. API가 표시되지 않으면 API를 사용 설정하세요.
    1. 페이지 상단에서 API 사용 설정을 선택하여 라이브러리 탭을 표시합니다. 또는 왼쪽 사이드 메뉴에서 라이브러리를 선택합니다.
    2. Places API를 검색한 후 결과 목록에서 선택합니다.
    3. 사용 설정을 선택합니다. 과정이 완료되면 Places API대시보드의 API 목록에 표시됩니다.

라이브러리 로드

장소 서비스는 기본 Maps JavaScript API 코드와 별도로, 필요한 모든 기능이 포함된 독립 라이브러리입니다. 이 라이브러리에 포함된 기능을 사용하려면 먼저 지도 API 부트스트랩 URL의 libraries 매개변수를 사용하여 로드해야 합니다.

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

자세한 내용은 라이브러리 개요를 참고하세요.

클래스 요약

API는 각각 AutocompleteSearchBox 클래스를 통해 추가할 수 있는 두 가지 유형의 자동 완성 위젯을 제공합니다. 또한 AutocompleteService 클래스를 사용하여 자동 완성 결과를 프로그래매틱 방식으로 가져올 수도 있습니다(Maps JavaScript API 참조: AutocompleteService 클래스 참고).

다음은 사용 가능한 클래스의 요약입니다.

  • Autocomplete는 웹페이지에 텍스트 입력란을 추가하고 해당 입력란의 문자 입력을 모니터링합니다. 사용자가 텍스트를 입력함에 따라 자동 완성이 드롭다운 선택 목록 형식으로 장소 예상 검색어를 반환합니다. 사용자가 목록에서 장소를 선택하면 장소에 대한 정보가 자동 완성 객체에 반환되며 애플리케이션에서 정보를 가져올 수 있습니다. 자세한 내용은 아래를 참고하세요.
    자동 완성 텍스트 필드 및 사용자가 검색어를 입력함에 따라 제공되는 장소 예상 검색어 선택 목록.
    그림 1: 자동 완성 텍스트 필드 및 선택 목록
    완성된 주소 양식
    그림 2: 완성된 주소 양식
  • SearchBoxAutocomplete와 거의 동일한 방식으로 웹페이지에 텍스트 입력란을 추가합니다. 차이점은 다음과 같습니다.
    • 주요 차이는 선택 목록에 표시되는 결과에 있습니다. SearchBox는 확장된 예상 검색어 목록을 제공하며 이 목록에는 Places API에서 정의한 장소 및 추천 검색어가 포함될 수 있습니다. 예를 들어 사용자가 'pizza in new'를 입력하는 경우 선택 목록에 'pizza in New York, NY' 문구 및 다양한 피자 매장 이름이 포함될 수 있습니다.
    • SearchBoxAutocomplete보다 적은 검색 제한 옵션을 제공합니다. SearchBox의 경우 지정된 LatLngBounds에 편중하여 검색할 수 있습니다. 자동 완성에서는 특정 국가 및 특정 장소 유형으로 검색을 제한할 수 있으며 경계를 설정할 수도 있습니다. 자세한 내용은 아래를 참고하세요.
    완성된 주소 양식
    그림 3: 검색어와 예상 검색어를 제공하는 SearchBox
    자세한 내용은 아래를 참고하세요.
  • AutocompleteService 객체를 만들면 예상 검색어를 프로그래매틱 방식으로 가져올 수 있습니다. getPlacePredictions()를 호출하여 일치하는 장소를 가져오거나 getQueryPredictions()를 호출하여 일치하는 장소와 추천 검색어를 가져오세요. 참고: AutocompleteService는 UI 컨트롤을 추가하지 않습니다. 대신 위의 메서드는 예상 검색어 객체의 배열을 반환합니다. 각 예상 검색어 객체에는 예상 검색어의 텍스트 및 참조 정보, 결과가 사용자 입력과 어떻게 일치하는지에 대한 세부정보가 포함됩니다. 자세한 내용은 아래를 참고하세요.

자동 완성 위젯 추가

Autocomplete는 웹페이지에 텍스트 입력란을 만들고 UI 선택 목록에 장소의 예상 검색어를 제공하고 getPlace() 요청에 대한 응답에 장소 세부정보를 반환합니다. 선택 목록의 각 항목은 Places API에 의해 정의된 단일 장소에 해당합니다.

Autocomplete 생성자는 다음 두 인수를 사용합니다.

  • text 유형의 HTML input 요소. 자동 완성 서비스가 모니터링하고 결과를 첨부하는 입력란입니다.
  • AutocompleteOptions 인수(선택사항). 다음과 같은 속성을 포함할 수 있습니다.
    • 사용자가 선택한 PlaceResultPlace Details 응답에 포함될 데이터 fields의 배열. 속성이 설정되어 있지 않거나 ['ALL']이 전달되는 경우 사용 가능한 모든 입력란이 반환되고 청구됩니다(프로덕션 배포의 경우 권장되지 않습니다). 필드의 목록은 PlaceResult를 참고하세요.
    • 지원되는 유형에 나열된 대로 명시적 유형 또는 유형 모음을 지정하는 types의 배열. 유형을 지정하지 않으면 모든 유형이 반환됩니다.
    • bounds는 장소를 검색할 영역을 지정하는 google.maps.LatLngBounds 객체입니다. 이 경계 안에 포함된 장소에 편중되지만 이 장소만으로 제한되지는 않는 결과가 나옵니다.
    • strictBounds는 API가 지정된 bounds로 정의된 지역 내에 있는 장소만 반환해야 하는지 여부를 지정하는 boolean입니다. API는 결과가 사용자 입력과 일치하더라도 이 지역 외부의 결과를 반환하지 않습니다.
    • componentRestrictions를 사용하여 결과를 특정 그룹으로 제한할 수 있습니다. 현재 componentRestrictions를 사용하여 최대 5개의 국가로 필터링할 수 있습니다. 국가는 2자리 ISO 3166-1 Alpha-2 호환 국가 코드로 전달해야 합니다. 여러 국가를 하나의 국가 코드 목록으로 전달해야 합니다.

      참고: 국가 코드가 포함된 예기치 않은 결과가 반환되면 원하는 국가, 종속 지역, 특별 관심 지역이 포함된 코드를 사용하고 있는지 확인하세요. 코드 정보는 위키백과: ISO 3166 국가 코드 목록 또는 ISO 온라인 탐색 플랫폼에서 확인할 수 있습니다.

    • placeIdOnlyAutocomplete 위젯이 장소 ID만 가져오도록 하는 데 사용할 수 있습니다. Autocomplete 객체에서 getPlace()를 호출할 때 제공되는 PlaceResult에는 place id, types, name 속성만 설정됩니다. 반환된 장소 ID를 장소, 지오코딩, 경로 또는 거리 행렬 서비스 호출에 사용할 수 있습니다.

자동 완성 예상 검색어 제한

기본적으로 Place Autocomplete는 사용자 위치 근처의 예상 검색어에 편중된 모든 장소 유형을 표시하며 사용자가 선택한 장소의 사용 가능한 모든 데이터 필드를 가져옵니다. 사용 사례를 기반으로 더 관련성 높은 예상 검색어를 표시하려면 Place Autocomplete 옵션을 설정하세요.

생성 시 옵션 설정

Autocomplete 생성자는 AutocompleteOptions 매개변수를 사용하여 위젯을 만들 때 제약 조건을 설정합니다. 다음 예에서는 bounds, componentRestrictions, types 옵션을 설정하여 establishment 유형의 장소를 요청함으로써, 지역 내의 장소를 우선 검색하도록 하고 미국 내 장소만으로 예상 검색어를 제한합니다. fields 옵션을 설정하여 사용자가 선택한 장소에 대해 반환할 정보를 지정할 수 있습니다.

기존 위젯의 옵션 값을 변경하려면 setOptions()를 호출하세요.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

자바스크립트

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

데이터 필드 지정

필요하지 않은 Places Data SKU에 대해 요금이 청구되지 않도록 데이터 필드를 지정하세요. 이전 예에 표시된 대로 위젯 생성자에 전달되는 AutocompleteOptionsfields 속성을 포함하거나 기존 Autocomplete 객체에서 setFields()를 호출하세요.

autocomplete.setFields(["place_id", "geometry", "name"]);

자동 완성을 위한 상세 검색 및 검색 영역 경계 정의

다음과 같은 방식으로 대략적인 위치나 지역에 편중된 자동 완성 결과를 얻을 수 있습니다.

  • Autocomplete 객체 생성 시 경계 설정
  • 기존 Autocomplete의 경계 변경
  • 지도의 표시 영역에 경계 설정
  • 경계로 검색 제한
  • 특정 국가로 검색 제한

이전 예에서는 생성 시 경계를 설정하는 방법을 보여줍니다. 다음 예에서는 다른 상세 검색 방법을 보여줍니다.

기존 자동 완성의 경계 변경

setBounds()를 호출하여 기존 Autocomplete의 검색 영역을 직사각형 경계로 변경합니다.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

자바스크립트

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
지도의 표시 영역으로 경계 설정

bindTo()를 사용하면 표시 영역이 변경되는 동안에도 지도의 표시 영역에 편중된 결과를 얻을 수 있습니다.

TypeScript

autocomplete.bindTo("bounds", map);

자바스크립트

autocomplete.bindTo("bounds", map);

unbind()를 사용하여 자동 완성 예상 검색어를 지도의 표시 영역에서 바인딩 해제합니다.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

자바스크립트

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

예 보기

현재 경계로 검색 제한

strictBounds 옵션을 설정하여 지도 표시 영역 또는 직사각형 경계를 기반으로 결과를 현재 경계로 제한합니다.

autocomplete.setOptions({ strictBounds: true });
특정 국가로 예상 검색어 제한

componentRestrictions 옵션을 사용하거나 setComponentRestrictions()를 호출하여 자동 완성 검색을 최대 다섯 개의 특정 국가로 제한할 수 있습니다.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

자바스크립트

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

예 보기

장소 유형 제한

types 옵션을 사용하거나 setTypes()를 호출하여 특정 장소 유형으로 예상 검색어를 제한할 수 있습니다. 이 제약 조건은 장소 유형에 나열되는 유형 또는 유형 모음을 지정합니다. 제약 조건을 지정하지 않으면 모든 유형이 반환됩니다.

types 옵션의 값 또는 setTypes()에 전달된 값의 경우 다음 중 하나를 지정할 수 있습니다.

  • 장소 유형표 1 또는 표 2에 있는 최대 다섯 개의 값이 포함된 배열. 예:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    또는

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • 장소 유형표 3에 있는 필터. 표 3의 값 하나만 지정할 수 있습니다.

다음과 같은 경우 요청이 거부됩니다.

  • 여섯 개 이상의 유형을 지정하는 경우
  • 인식할 수 없는 유형을 지정하는 경우
  • 표 1 또는 표 2의 유형을 표 3의 필터와 혼합하는 경우

Place Autocomplete 데모는 여러 장소 유형 간 예상 검색어의 차이를 보여줍니다.

데모 보기

장소 정보 가져오기

사용자가 자동 완성 텍스트 입력란에 첨부된 예상 검색어에서 장소를 선택하면 서비스가 place_changed 이벤트를 실행합니다. 장소 세부정보를 가져오는 방법은 다음과 같습니다.

  1. place_changed 이벤트의 이벤트 핸들러를 만들고 Autocomplete 객체에서 addListener()를 호출하여 핸들러를 추가합니다.
  2. Autocomplete 객체에서 Autocomplete.getPlace()를 호출하여 PlaceResult 객체를 가져와 선택된 장소에 대한 추가 정보를 가져옵니다.

기본적으로 사용자가 장소를 선택하면 자동 완성이 선택된 장소의 사용 가능한 모든 데이터 필드를 반환하며 그에 따라 요금이 청구됩니다. 반환할 장소 데이터 필드를 지정하려면 Autocomplete.setFields()를 사용하세요. 요청할 수 있는 장소 데이터 필드 목록이 포함된 PlaceResult 객체에 대해 자세히 알아보세요. 필요하지 않은 데이터에 비용을 지불하지 않으려면 Autocomplete.setFields()를 호출하여 사용할 장소 데이터만 지정하세요.

name 속성에는 Place Autocomplete 예상 검색어의 description이 포함됩니다. description에 관한 자세한 내용은 Place Autocomplete 문서를 참고하세요.

주소 양식의 경우 구조화된 형식으로 주소를 가져오는 것이 유용합니다. 선택된 장소의 구조화된 주소를 반환하려면 Autocomplete.setFields()를 호출하고 address_components 필드를 지정하세요.

다음 예에서는 자동 완성을 사용하여 주소 양식의 필드를 채웁니다.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

자바스크립트

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

예 보기

자리표시자 텍스트 맞춤설정

기본적으로 자동 완성 서비스가 생성한 텍스트 입력란에는 표준 자리표시자 텍스트가 포함됩니다. 텍스트를 수정하려면 input 요소에 placeholder 속성을 설정하세요.

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

참고: 기본 자리표시자 텍스트는 자동으로 현지화됩니다. 자리표시자 값을 직접 지정하는 경우 애플리케이션에서 해당 값의 현지화를 처리해야 합니다. Google Maps JavaScript API에서 사용할 언어를 선택하는 방법에 관한 자세한 내용은 현지화에 관한 문서를 참고하세요.

위젯 모양을 맞춤설정하려면 자동 완성 및 SearchBox 위젯 스타일 지정을 참고하세요.

SearchBox를 사용하면 '의정부 부대찌개' 또는 '홍대 근처 클럽'과 같은 텍스트 기반 지역 검색을 실행할 수 있습니다. 텍스트 입력란에 SearchBox를 연결할 수 있습니다. 그러면 텍스트를 입력할 때 서비스에서 예상 검색어를 드롭다운 선택 목록의 형태로 반환합니다.

SearchBox는 확장된 예상 검색어 목록을 제공하며 이 목록에는 Places API에서 정의한 장소 및 추천 검색어가 포함될 수 있습니다. 예를 들어 사용자가 'pizza in new'를 입력하는 경우 선택 목록에 'pizza in New York, NY' 문구 및 다양한 피자 매장 이름이 포함될 수 있습니다. 사용자가 목록에서 장소를 선택하면 해당 장소에 대한 정보가 SearchBox 객체에 반환되며 애플리케이션에서 정보를 가져올 수 있습니다.

SearchBox 생성자는 다음 두 인수를 사용합니다.

  • text 유형의 HTML input 요소. SearchBox 서비스가 모니터링하고 결과를 첨부하는 입력란입니다.
  • options 인수: bounds 속성을 포함할 수 있습니다. bounds는 장소를 검색할 영역을 지정하는 google.maps.LatLngBounds 객체입니다. 이 경계 안에 포함된 장소에 편중되지만 이 장소만으로 제한되지는 않는 결과가 나옵니다.

다음 코드에서는 경계 매개변수를 사용하여 위도/경도 좌표를 통해 지정된 특정 지리적 영역 내의 장소에 편중된 결과를 얻습니다.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

SearchBox의 검색 영역 변경

기존 SearchBox의 검색 영역을 변경하려면 SearchBox 객체의 setBounds()를 호출하고 관련 LatLngBounds 객체를 전달하세요.

예 보기

장소 정보 가져오기

사용자가 검색창에 연결된 예상 검색어에서 항목을 선택하면 서비스에서 places_changed 이벤트를 실행합니다. SearchBox 객체에서 getPlaces()를 호출하여 여러 예상 검색어가 포함된 배열을 검색할 수 있습니다. 각 예상 검색어는 PlaceResult 객체입니다.

PlaceResult 객체에 대한 자세한 내용은 장소 세부정보 결과에 관한 문서를 참고하세요.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

자바스크립트

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

예 보기

위젯 모양을 맞춤설정하려면 자동 완성 및 SearchBox 위젯 스타일 지정을 참고하세요.

프로그래매틱 방식으로 Place Autocomplete 서비스 예상 검색어 가져오기

프로그래매틱 방식으로 예상 검색어를 가져오려면 AutocompleteService 클래스를 사용하세요. AutocompleteService는 UI 컨트롤을 추가하지 않습니다. 대신 예상 검색어 객체의 배열을 반환합니다. 각 예상 검색어 객체에는 예상 검색어 텍스트, 참조 정보 및 결과가 사용자 입력과 어떻게 일치하는지에 대한 세부정보가 포함됩니다. 이 방법은 위에서 설명한 AutocompleteSearchBox에서 제공하는 것보다 상세하게 사용자 인터페이스를 관리하고자 하는 경우에 유용합니다.

AutocompleteService는 다음 메서드를 제공합니다.

  • getPlacePredictions()는 장소 예상 검색어를 반환합니다. 참고: '장소'는 Places API에 정의된 것처럼 시설, 지리적 위치 또는 유명한 관심 장소가 될 수 있습니다.
  • getQueryPredictions()는 확장된 예상 검색어 목록을 반환하며 이 목록에는 Places API에서 정의한 장소 및 추천 검색어가 포함될 수 있습니다. 예를 들어 사용자가 'pizza in new'를 입력하는 경우 선택 목록에 'pizza in New York, NY' 문구 및 다양한 피자 매장 이름이 포함될 수 있습니다.

위의 두 메서드 모두 다음과 같은 형식의 예상 검색어 객체 배열을 반환합니다.

  • description은 일치하는 예상 검색어입니다.
  • distance_meters는 지정된 AutocompletionRequest.origin에서 장소까지의 거리(미터)입니다.
  • matched_substrings에는 사용자 입력의 요소와 일치하는 description에 있는 하위 문자열의 집합이 포함됩니다. 이 객체는 애플리케이션에서 이러한 하위 문자열을 강조표시하는 데 유용합니다. 대부분의 경우 쿼리는 description 필드의 하위 문자열로 표시됩니다.
    • length는 하위 문자열의 길이입니다.
    • offset은 일치하는 하위 문자열이 표시되는 description 문자열의 시작 부분부터 측정한 문자 오프셋입니다.
  • place_id는 장소를 고유하게 나타내는 텍스트 식별자입니다. 장소에 관한 정보를 가져오려면 장소 세부정보 요청placeId 필드에 이 식별자를 전달하세요. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.
  • terms는 쿼리의 요소가 포함된 배열입니다. 장소의 경우 각 요소는 대개 주소의 한 부분을 구성합니다.
    • offset은 일치하는 하위 문자열이 표시되는 description 문자열의 시작 부분부터 측정한 문자 오프셋입니다.
    • value는 일치하는 검색어입니다.

아래 예에서는 'pizza near'라는 문구에 대한 쿼리 예상 검색어 요청을 실행하고 결과를 목록으로 표시합니다.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

샘플 사용해 보기

예 보기

세션 토큰

AutocompleteService.getPlacePredictions()는 세션 토큰을 사용하여 결제 목적의 자동 완성 요청을 그룹화합니다. 세션 토큰은 사용자 자동 완성 검색의 쿼리 및 선택 단계를 결제 목적의 개별 세션으로 그룹화합니다. 세션은 사용자가 쿼리를 입력하기 시작하면 시작되고 장소를 선택하면 종료됩니다. 세션마다 여러 개의 쿼리가 포함될 수 있으며 하나의 장소가 선택됩니다. 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱에서 각 세션에 대해 새 토큰을 생성해야 합니다. 모든 자동 완성 세션에 세션 토큰을 사용하는 것이 좋습니다. sessionToken 매개변수가 생략되거나 세션 토큰을 재사용하는 경우 세션 토큰이 제공되지 않은 것처럼 세션에 대해 요금이 청구됩니다(각 요청에 대해 별도로 요금이 청구됩니다).

동일한 세션 토큰을 사용하여 AutocompleteService.getPlacePredictions() 호출의 결과로 생성된 장소에 대해 단일 장소 세부정보 요청을 할 수 있습니다. 이 경우 자동 완성 요청이 장소 세부정보 요청과 결합되며 호출에 대해 일반 장소 세부정보 요청으로 요금이 청구됩니다. 자동 완성 요청에는 요금이 부과되지 않습니다.

새 세션마다 고유한 세션 토큰을 전달해야 합니다. 둘 이상의 자동 완성 세션에 동일한 토큰을 사용하면 해당 자동 완성 세션이 무효화되며 유효하지 않은 세션의 모든 자동 완성 요청에 대해 요청별 자동 완성 SKU를 사용하여 개별적으로 요금이 청구됩니다. 세션 토큰에 대해 자세히 알아보세요.

다음 예에서는 세션 토큰을 만든 다음 AutocompleteService에 전달합니다(displaySuggestions() 함수는 간결성을 위해 생략했습니다).

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

새 세션마다 고유한 세션 토큰을 전달해야 합니다. 두 개 이상의 세션에 동일한 토큰을 사용하면 각 요청에 대해 개별적으로 요금이 청구됩니다.

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

자동 완성 및 SearchBox 위젯 스타일 지정

기본적으로 AutocompleteSearchBox에서 제공하는 UI 요소는 Google 지도에 포함되도록 스타일이 지정됩니다. 자신의 사이트에 맞게 스타일링을 조정할 수도 있습니다. 다음과 같은 CSS 클래스를 사용할 수 있습니다. 아래에 나열된 모든 클래스는 AutocompleteSearchBox 위젯에 모두 적용됩니다.

자동 완성 및 SearchBox 위젯용 CSS 클래스의 그래픽 일러스트레이션
자동 완성 및 SearchBox 위젯용 CSS 클래스
CSS 클래스 설명
pac-container Place Autocomplete 서비스에서 반환한 예상 검색어 목록이 포함된 시각적 요소. 이 목록은 Autocomplete 또는 SearchBox 위젯 아래 드롭다운 목록으로 표시됩니다.
pac-icon 예상 검색어 목록에서 각 항목의 왼쪽에 표시되는 아이콘.
pac-item Autocomplete 또는 SearchBox 위젯에서 제공하는 예상 검색어 목록의 항목.
pac-item:hover 사용자가 마우스 포인터로 가리키는 항목.
pac-item-selected 사용자가 키보드로 선택한 항목. 참고: 선택된 항목은 이 클래스 및 pac-item 클래스의 멤버입니다.
pac-item-query 예상 검색어의 주요 부분인 pac-item 내부의 범위. 지리적 위치의 경우 '시드니'와 같은 장소 이름이나 '10. King Street'와 같은 도로명과 번지가 포함됩니다. 'pizza in New York'과 같은 텍스트 기반 검색의 경우 쿼리의 전체 텍스트가 포함됩니다. 기본적으로 pac-item-query는 검은색으로 지정됩니다. pac-item에 추가 텍스트가 있으면 pac-item-query의 외부에 있으며 pac-item의 스타일을 상속합니다. 기본적으로 색상은 회색으로 지정됩니다. 추가 텍스트는 일반적으로 주소입니다.
pac-matched 사용자의 입력과 일치하는 반환된 예상 검색어의 일부. 기본적으로 일치하는 텍스트는 굵은 텍스트로 강조표시됩니다. 일치하는 텍스트는 pac-item 내 어디에나 있을 수 있습니다. pac-item-query의 일부일 필요는 없으며 pac-item-query 내부와 pac-item의 나머지 텍스트에 부분적으로 포함될 수 있습니다.

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달러인 세션 토큰(프로그래매틱 방식으로 또는 자바스크립트 ,Android 또는iOS에 내장하여) 및 요청하는 장소 데이터 필드에 따라 관련 장소 데이터 SKU를 사용해야 합니다.1

위젯 구현
세션 관리는 자바스크립트, 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

위젯 구현
세션 관리는 자바스크립트, 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'처럼 도로 구간 접두사가 있는 주소를 입력하는 경우

사용량 한도 및 정책

할당량

할당량 및 가격 정보는 Places API의 사용량 및 결제 문서를 참고하세요.

정책

장소 라이브러리, Maps JavaScript API는 Places API에 설명된 정책에 따라 사용해야 합니다.