새로운 지도 스타일이 곧 Google Maps Platform에 제공될 예정입니다. 이 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트와 지도 환경 및 사용성 개선사항이 포함됩니다. 모든 지도 스타일이 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 더 일찍 선택하는 방법에 대한 자세한 내용은 Google Maps Platform용 새로운 지도 스타일을 참고하세요.

Place Autocomplete(실험용)

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

사전 준비 사항

Place Autocomplete(신규)(실험용)에 오신 것을 환영합니다. 텍스트 검색(미리보기)을 사용하려면 Google Cloud 프로젝트에서 'Places API'를 사용 설정하고, 부트스트랩 로더에서 알파 채널(v: "alpha")을 지정해야 합니다. 자세한 내용은 시작하기를 참고하세요.

새로운 기능

Place Autocomplete(실험용)가 다음과 같이 개선되었습니다.

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

웹페이지 또는 Google 지도에 자동 완성 위젯을 추가할 수 있습니다. 자동 완성 위젯은 텍스트 입력란을 만들고 UI 선택 목록에 장소 예상 검색어를 제공하며 gmp-placeselect 리스너를 통해 사용자 클릭에 대한 응답으로 장소 세부정보를 반환합니다. 이 섹션에서는 웹페이지 또는 Google 지도에 자동 완성 위젯을 추가하는 방법을 설명합니다.

웹페이지에 자동 완성 위젯을 추가하려면 새 input 요소를 만든 다음 이 요소를 사용하여 새 google.maps.places.PlaceAutocompleteElement를 만들고 다음 예와 같이 페이지에 추가합니다.

TypeScript

// Request needed libraries.
//@ts-ignore
const [{ Map }] = await Promise.all([
    google.maps.importLibrary("places"),
]);
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
document.body.appendChild(placeAutocomplete);index.ts

JavaScript

// Request needed libraries.
//@ts-ignore
const [{ Map }] = await Promise.all([google.maps.importLibrary("places")]);
// Create the input HTML element, and append it.
//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
document.body.appendChild(placeAutocomplete);
index.js

전체 코드 예 보기

지도에 자동 완성 위젯을 추가하려면 새 input 요소를 만들고 이 요소를 사용하여 새 google.maps.places.PlaceAutocompleteElement 인스턴스를 만든 다음 PlaceAutocompleteElement를 div에 추가하고 다음 예와 같이 맞춤 컨트롤로 지도에 푸시합니다.

TypeScript

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
//@ts-ignore
placeAutocomplete.id = 'place-autocomplete-input';

const card = document.getElementById('place-autocomplete-card') as HTMLElement;
//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);index.ts

JavaScript

//@ts-ignore
const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

//@ts-ignore
placeAutocomplete.id = "place-autocomplete-input";

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

//@ts-ignore
card.appendChild(placeAutocomplete);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);index.js

전체 코드 예 보기

자동 완성 예상 검색어 제한

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

결과를 제한하면 자동 완성 위젯이 제한 지역 밖의 모든 결과를 무시합니다. 일반적인 방법은 결과를 지도 경계로 제한하는 것입니다. 결과를 상세 검색하면 자동 완성 위젯이 지정된 지역 내 결과를 표시하지만 일부 일치 항목이 해당 지역을 벗어날 수 있습니다.

국가별 장소 검색 제한

장소 검색을 하나 이상의 특정 국가로 제한하려면 다음 스니펫에 표시된 대로 componentRestrictions 속성을 사용하여 국가 코드를 지정합니다.

const pac = new google.maps.places.PlaceAutocompleteElement({
  inputElement: input,
  componentRestrictions: {country: ['us', 'au']},
});

장소 검색을 지도 경계로 제한

장소 검색을 지도 경계로 제한하려면 다음 스니펫과 같이 locationRestrictions 속성을 사용하여 경계를 추가합니다.

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

지도 경계로 제한할 때는 경계가 변경될 때 경계를 업데이트하는 리스너를 추가해야 합니다.

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

locationRestriction을 삭제하려면 null로 설정합니다.

장소 검색결과 상세 검색

다음과 같이 locationBias 속성을 사용하고 반경을 전달하여 장소 검색결과를 원 영역에 배치합니다.

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  inputElement: input,
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

locationBias를 삭제하려면 null로 설정합니다.

장소 검색결과를 특정 유형으로 제한

다음과 같이 types 속성을 사용하고 하나 이상의 유형을 지정하여 장소 검색결과를 특정 유형으로 제한합니다.

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  inputElement: input,
  types: ['establishment'],
});

지원되는 유형의 전체 목록은 표 3: Place Autocomplete 요청 시 지원되는 유형을 참고하세요.

장소 세부정보 가져오기

선택한 장소의 장소 세부정보를 가져오려면 다음 예와 같이 PlaceAutocompleteElement에 gmp-place-select 리스너를 추가합니다.

TypeScript

// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
    await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

    selectedPlaceTitle.textContent = 'Selected Place:';
    selectedPlaceInfo.textContent = JSON.stringify(
        place.toJSON(), /* replacer */ null, /* space */ 2);
});index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
  await place.fetchFields({
    fields: ["displayName", "formattedAddress", "location"],
  });
  selectedPlaceTitle.textContent = "Selected Place:";
  selectedPlaceInfo.textContent = JSON.stringify(
    place.toJSON(),
    /* replacer */ null,
    /* space */ 2,
  );
});index.js

전체 코드 예 보기

이전 예에서는 이벤트 리스너가 장소 클래스 객체를 반환합니다. place.fetchFields()를 호출하여 애플리케이션에 필요한 장소 세부정보 데이터 필드를 가져옵니다.

다음 예의 리스너는 장소 정보를 요청하고 이를 지도에 표시합니다.

TypeScript

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
    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;
});index.ts

JavaScript

// Add the gmp-placeselect listener, and display the results on the map.
//@ts-ignore
placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
  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;
});index.js

전체 코드 예 보기

선택한 장소에 대한 지오코딩 결과 가져오기

선택한 장소의 지오코딩 결과를 가져오려면 다음 스니펫과 같이 google.maps.Geocoder를 사용하여 위치를 가져옵니다.

const map = new google.maps.Map(document.getElementById('map'), {
  center: {lat: 50.064192, lng: -130.605469},
  zoom: 3,
});

const marker = new google.maps.Marker({map});
const inputElement = document.getElementById('pac-input');
const autocomplete = new google.maps.places.PlaceAutocompleteElement({inputElement});
const geocoder = new google.maps.Geocoder();

autocomplete.addListener('gmp-placeselect', async ({prediction: place}) => {
  const results = await geocoder.geocode({place.id});
  marker.setPlace({
    placeId: place.id,
    location: results[0].geometry.location,
  });
});

지도의 예

이 섹션에는 이 페이지에 표시된 지도 예의 전체 코드가 포함되어 있습니다.

자동 완성 요소

이 예에서는 웹페이지에 자동 완성 위젯을 추가하고 선택한 각 장소에 대한 결과를 표시합니다.

TypeScript

async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    const [{ Map }] = await Promise.all([
        google.maps.importLibrary("places"),
    ]);
    // Create the input HTML element, and append it.
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-placeselect listener, and display the results.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
        await place.fetchFields({ fields: ['displayName', 'formattedAddress', 'location'] });

        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(), /* replacer */ null, /* space */ 2);
    });
}

initMap();index.ts

JavaScript

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  const [{ Map }] = await Promise.all([google.maps.importLibrary("places")]);
  // Create the input HTML element, and append it.
  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  document.body.appendChild(placeAutocomplete);

  // Inject HTML UI.
  const selectedPlaceTitle = document.createElement("p");

  selectedPlaceTitle.textContent = "";
  document.body.appendChild(selectedPlaceTitle);

  const selectedPlaceInfo = document.createElement("pre");

  selectedPlaceInfo.textContent = "";
  document.body.appendChild(selectedPlaceInfo);
  // Add the gmp-placeselect listener, and display the results.
  //@ts-ignore
  placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location"],
    });
    selectedPlaceTitle.textContent = "Selected Place:";
    selectedPlaceInfo.textContent = JSON.stringify(
      place.toJSON(),
      /* replacer */ null,
      /* space */ 2,
    );
  });
}

initMap();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

p {
  font-family: Roboto, sans-serif;
  font-weight: bold;
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete element</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 style="font-family: roboto, sans-serif">Search for a place here:</p>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "alpha"});</script>
  </body>
</html>index.html

샘플 사용해 보기

JSFiddle.net Google Cloud Shell

지도 자동 완성

이 예에서는 Google 지도에 자동 완성 위젯을 추가하는 방법을 보여줍니다.

TypeScript

let map: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function initMap(): Promise<void> {
    // Request needed libraries.
    //@ts-ignore
    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') as HTMLElement, {
        center: { lat: 40.749933, lng: -73.98633 },
        zoom: 13,
        mapId: '4504f8b37365c3d0',
        mapTypeControl: false,
    });
    //@ts-ignore
    const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();
    //@ts-ignore
    placeAutocomplete.id = 'place-autocomplete-input';

    const card = document.getElementById('place-autocomplete-card') as HTMLElement;
    //@ts-ignore
    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-placeselect listener, and display the results on the map.
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-placeselect', async ({ place }) => {
        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,
    });
}

initMap();index.ts

JavaScript

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  //@ts-ignore
  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,
  });

  //@ts-ignore
  const placeAutocomplete = new google.maps.places.PlaceAutocompleteElement();

  //@ts-ignore
  placeAutocomplete.id = "place-autocomplete-input";

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

  //@ts-ignore
  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-placeselect listener, and display the results on the map.
  //@ts-ignore
  placeAutocomplete.addEventListener("gmp-placeselect", async ({ place }) => {
    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,
  });
}

initMap();index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

#place-autocomplete-card {
  background-color: #fff;
  border-radius: 5px;
  box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
  margin: 10px;
  padding: 5px;
  font-family: Roboto, sans-serif;
  font-size: large;
  font-weight: bold;
}

#place-autocomplete {
  width: 250px;
}

#infowindow-content .title {
  font-weight: bold;
}

#map #infowindow-content {
  display: inline;
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete map</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>
    <div class="place-autocomplete-card" id="place-autocomplete-card">
      <p>Search for a place here:</p>
    </div>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "alpha"});</script>
  </body>
</html>index.html

샘플 사용해 보기

JSFiddle.net Google Cloud Shell

Place Autocomplete(실험용)

사전 준비 사항

새로운 기능

자동 완성 위젯 추가

웹페이지에 자동 완성 위젯 추가

TypeScript

JavaScript

지도에 자동 완성 위젯 추가

TypeScript

JavaScript

자동 완성 예상 검색어 제한

국가별 장소 검색 제한

장소 검색을 지도 경계로 제한

장소 검색결과 상세 검색

장소 검색결과를 특정 유형으로 제한

장소 세부정보 가져오기

TypeScript

JavaScript

TypeScript

JavaScript

선택한 장소에 대한 지오코딩 결과 가져오기

지도의 예

자동 완성 요소

TypeScript

JavaScript

CSS

HTML

샘플 사용해 보기

지도 자동 완성

TypeScript

JavaScript

CSS

HTML

샘플 사용해 보기