새 Place Autocomplete로 이전

유럽 경제 지역 (EEA) 개발자

청구서 수신 주소가 유럽 경제 지역에 있는 경우 2025년 7월 8일부터 Google Maps Platform EEA 서비스 약관 이 서비스 이용에 적용됩니다. 기능은 리전에 따라 다릅니다. 자세히 알아보기

Place Autocomplete는 Maps JavaScript API에 포함되어 있는 장소 라이브러리의 기능입니다. 자동 완성을 사용하여 애플리케이션에 Google 지도 검색창의 검색 전 입력 기능을 제공할 수 있습니다.

이 페이지에서는 기존 Place Autocomplete 기능과 새로운 Place Autocomplete 기능의 차이점을 설명합니다. 두 버전 모두 자동 완성을 통합하는 일반적인 방법에는 두 가지가 있습니다.

• 프로그래매틱 인터페이스: 자동 완성 환경을 더 세부적으로 맞춤설정하고 제어하려는 개발자에게 적합합니다.
• Place Autocomplete 위젯: 지도 또는 웹페이지에 삽입할 수 있는 검색창입니다.

자동 완성 프로그래매틱 인터페이스

다음 표에는 Places Autocomplete 서비스(기존)와 Autocomplete Data API (신규) 간의 프로그래매틱 Place Autocomplete 사용의 주요 차이점이 나열되어 있습니다.

PlacesService (기존)	Place (신규)
Place Autocomplete 서비스 참조	Autocomplete Data (신규) 참조
AutocompletionRequest	AutocompleteRequest
AutocompleteService.getPlacePredictions	AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction	PlacePrediction
메서드에서는 콜백을 사용하여 결과 객체와 PlacesServiceStatus 응답을 처리해야 합니다.	Promise를 사용하며 비동기식으로 작동합니다.
메서드에는 PlacesServiceStatus 확인이 필요합니다.	필수 상태 확인이 없으며 표준 오류 처리를 사용할 수 있습니다. 자세히 알아보기
장소 데이터 필드는 Autocomplete 인스턴스가 생성될 때 옵션으로 설정됩니다.	장소 데이터 필드는 나중에 fetchFields()가 호출될 때 설정됩니다.
질문 예측이 지원됩니다 (SearchBox만 해당).	Autocomplete 클래스에서는 쿼리 예측을 사용할 수 없습니다.
고정된 장소 유형 및 장소 데이터 필드로 제한됩니다.	확장된 장소 유형 및 장소 데이터 필드에 액세스할 수 있습니다.

다음은 기존 및 새 Autocomplete API에서 모두 사용됩니다.

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

코드 비교 (프로그래매틱)

이 섹션에서는 자동 완성 코드를 비교하여 프로그래매틱 인터페이스의 Places 서비스와 Place 클래스 간의 차이점을 설명합니다.

자동 완성 예상 검색어 가져오기 (레거시)

기존 Places 서비스를 사용하면 Autocomplete 클래스에서 제공하는 것보다 사용자 인터페이스를 더 효과적으로 제어할 수 있도록 자동 완성 예상 검색어를 프로그래매틱 방식으로 가져올 수 있습니다. 다음 예시에서는 입력 값과 예측을 바이어스하기 위한 경계 집합으로 구성된 AutocompletionRequest를 사용하여 'par'에 대한 단일 요청이 이루어집니다. 이 예시에서는 AutocompletePrediction 인스턴스 목록을 반환하고 각 인스턴스의 설명을 표시합니다. 예시 함수는 세션 토큰을 생성하고 요청에 적용하기도 합니다.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    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 placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

• 프로그래매틱 방식으로 Place Autocomplete 서비스 예상 검색어 가져오기
• Place Autocomplete 예
• 세션 토큰
• AutocompletionRequest 참조
• AutocompletePrediction 참조

자동 완성 예상 검색어 가져오기 (신규)

새로운 Place 클래스를 사용하면 PlaceAutocompleteElement 클래스에서 제공하는 것보다 사용자 인터페이스를 더 세부적으로 제어할 수 있도록 자동 완성 예측을 프로그래매틱 방식으로 가져올 수도 있습니다. 다음 예에서는 입력 값과 예측에 바이어스를 적용하기 위한 경계 집합으로 구성된 AutocompleteRequest를 사용하여 'par'에 대한 단일 요청이 이루어집니다. 이 예에서는 placePrediction 인스턴스 목록을 반환하고 각 인스턴스의 설명을 표시합니다. 예시 함수는 세션 토큰을 생성하고 요청에 적용하기도 합니다.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

• Place Autocomplete Data API
• Place Autocomplete 데이터 예측 예
• Place Autocomplete 데이터 세션 예
• 세션 토큰
• AutocompleteRequest 인터페이스 참조
• AutocompleteSuggestion 클래스 참조
• PlacePrediction 클래스 참조

장소 자동 완성 위젯

다음 표에는 장소 서비스 (기존)와 장소 클래스(신규) 간의 자동 완성 위젯 사용의 주요 차이점이 나와 있습니다.

장소 서비스 (기존)	장소 (신규)
장소 예상 검색어를 위한 Autocomplete 클래스	장소 예상 검색어를 위한 PlaceAutocompleteElement 클래스
SearchBox 클래스 질문 예측	Autocomplete 클래스에서는 쿼리 예측을 사용할 수 없습니다.
기본 입력 자리표시자 텍스트만 현지화됩니다.	텍스트 입력 자리표시자, 예상 검색어 목록 로고, 장소 예상 검색어는 모두 지역 현지화를 지원합니다.
위젯은 setBounds() 또는 autocomplete.bindTo()를 사용하여 검색을 지정된 경계로 제한 (바이어스)하고 strictBounds를 사용하여 결과를 지정된 경계로 제한합니다.	위젯은 locationBias 속성을 사용하여 결과를 지정된 경계로 편향시키고 locationRestriction 속성을 사용하여 검색을 지정된 경계로 제한합니다.
위젯은 표준 HTML 입력 요소를 사용하여만 통합할 수 있습니다.	위젯은 표준 HTML 입력 요소 또는 gmp-place-autocomplete 요소를 사용하여 통합할 수 있습니다.
위젯을 사용할 때 사용자가 유효하지 않을 수 있는 항목 (예: '비스니랜드')을 요청할 수 있습니다. 이 경우를 명시적으로 처리해야 합니다.	위젯은 제공된 추천에 대한 결과만 반환하며 임의의 값에 대한 요청을 발행할 수 없습니다. 따라서 잠재적으로 잘못된 요청을 처리할 필요가 없습니다.
기존 PlaceResult 인스턴스를 반환합니다.	Place 인스턴스를 반환합니다.
장소 데이터 필드는 Autocomplete 객체의 옵션으로 설정됩니다.	사용자가 선택하고 fetchFields()가 호출되면 장소 데이터 필드가 설정됩니다.
고정된 장소 유형 및 장소 데이터 필드로 제한됩니다.	확장된 장소 유형 및 장소 데이터 필드에 액세스할 수 있습니다.

코드 비교 (위젯)

이 섹션에서는 자동 완성 코드를 비교하여 기존 Place Autocomplete 위젯과 새로운 Place Autocomplete 요소의 차이점을 설명합니다.

Place Autocomplete 위젯 (기존)

장소 서비스는 Autocomplete 및 SearchBox 클래스를 사용하여 추가할 수 있는 두 가지 유형의 자동 완성 위젯을 제공합니다. 각 위젯은 지도 컨트롤로 지도에 추가하거나 웹페이지에 직접 삽입할 수 있습니다. 다음 코드 예는 Autocomplete 위젯을 지도 컨트롤로 삽입하는 방법을 보여줍니다.

• Autocomplete 위젯 생성자는 다음 두 인수를 사용합니다.
  • text 유형의 HTML input 요소. 자동 완성 서비스가 모니터링하고 결과를 첨부하는 입력란입니다.
  • 선택적 AutocompleteOptions 인수입니다. 여기서 쿼리를 제한하는 추가 옵션을 지정할 수 있습니다.
• 경계를 설정하려면 autocomplete.bindTo()를 호출하여 Autocomplete 인스턴스를 지도에 명시적으로 바인딩하면 됩니다.
• 자동 완성 옵션에서 장소 데이터 필드를 지정합니다.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

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

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

• Place Autocomplete 문서
• Place Autocomplete 위젯 예
• 장소 검색창 예
• Autocomplete 클래스 참조

Place Autocomplete 위젯 (신규)

장소 클래스는 PlaceAutocompleteElement를 제공합니다. 이는 HTMLElement 하위 클래스로, 지도에 지도 컨트롤로 추가하거나 웹페이지에 직접 삽입할 수 있는 UI 구성요소를 제공합니다. 다음 코드 예는 PlaceAutocompleteElement 위젯을 지도 컨트롤로 삽입하는 방법을 보여줍니다.

Place Autocomplete 위젯이 다음과 같이 개선되었습니다.

• 자동 완성 위젯 UI가 텍스트 입력 자리표시자, 예상 검색어 목록 로고, 장소 예상 검색어의 지역 현지화 (RTL 언어 포함)를 지원합니다.
• 스크린 리더 및 키보드 상호작용에 대한 지원을 포함하여 접근성이 개선되었습니다.
• 자동 완성 위젯이 반환된 객체의 처리를 간소화하기 위해 새 Place 클래스를 반환합니다.
• 휴대기기 및 소형 화면에 대한 지원이 개선되었습니다.
• 성능이 향상되고 그래픽 모양이 개선되었습니다.

주요 구현 차이점은 다음과 같습니다.

• PlaceAutocompleteElement는 자체 입력 필드를 제공하며 기존 입력 요소를 제공받는 대신 HTML 또는 JavaScript를 사용하여 페이지에 직접 삽입됩니다.
• 쿼리 예측은 Autocomplete 클래스에서 사용할 수 없습니다.
• PlaceAutocompleteElement은 PlaceAutocompleteElementOptions를 사용하여 구성됩니다.
  • 장소 데이터 필드는 선택 시간 (fetchFields()가 호출될 때)에 지정됩니다.
• locationBounds 또는 locationRestriction 옵션을 사용하여 경계를 설정합니다.

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  const placeAutocomplete =
    new google.maps.places.PlaceAutocompleteElement({
      locationRestriction: map.getBounds(),
    });

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  // Create the marker and infowindow.
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});

  // Add the gmp-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( place ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location"],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      map.fitBounds(place.viewport);
    } else {
      map.setCenter(place.location);
      map.setZoom(17);
    }

    let content =
      '<div id="infowindow-content">' +
      '<span id="place-displayname" class="title">' +
      place.displayName +
      '</span><br />' +
      '<span id="place-address">' +
      place.formattedAddress +
      '</span>' +
      '</div>';

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}

• Place Autocomplete 위젯 (미리보기) 문서
• Place Autocomplete 위젯 예
• Place Autocomplete 요소 예
• PlaceAutocompleteElement 클래스 참조