새로운 지도 스타일이 곧 Google Maps Platform에 제공될 예정입니다. 이 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트와 지도 환경 및 사용성 개선사항이 포함됩니다. 모든 지도 스타일이 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 더 일찍 선택하는 방법에 대한 자세한 내용은 Google Maps Platform용 새로운 지도 스타일을 참고하세요.
이 페이지에서는 Maps JavaScript API와 함께 사용할 수 있는 클라이언트 측 라이브러리를 설명합니다. 서버에서 Places API 웹 서비스를 사용하려면 Google 지도 서비스용 Node.js 클라이언트를 참고하세요. 이 링크의 페이지에는 Google 지도 서비스용 Java 클라이언트, Python 클라이언트, Go 클라이언트도 소개되어 있습니다.
소개
자동 완성은 Maps JavaScript API에 포함되어 있는 장소 라이브러리의 기능입니다. 자동 완성을 사용하여 애플리케이션에 Google 지도 검색창의 검색 전 입력 기능을 제공할 수 있습니다.
자동 완성 서비스는 전체 단어 및 하위 문자열을 일치시켜 장소 이름, 주소 및 Plus Code를 결정할 수 있습니다. 따라서 사용자가 입력할 때 애플리케이션에서 쿼리를 전송하여 즉시 장소 예상 검색어를 제공할 수 있습니다. Places API에 정의된 것처럼 '장소'는 시설, 지리적 위치 또는 유명한 관심 장소가 될 수 있습니다.
시작하기
Maps JavaScript API에서 장소 라이브러리를 사용하려면 먼저 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트의 Google Cloud 콘솔에서 Places API를 사용 설정해야 합니다.
API는 각각 Autocomplete 및 SearchBox 클래스를 통해 추가할 수 있는 두 가지 유형의 자동 완성 위젯을 제공합니다.
또한 AutocompleteService 클래스를 사용하여 자동 완성 결과를 프로그래매틱 방식으로 가져올 수도 있습니다(Maps JavaScript API 참조: AutocompleteService 클래스 참고).
다음은 사용 가능한 클래스의 요약입니다.
Autocomplete는 웹페이지에 텍스트 입력란을 추가하고 해당 입력란의 문자 입력을 모니터링합니다. 사용자가 텍스트를 입력할 때 자동 완성이 드롭다운 선택 목록 형식으로 장소 예상 검색어를 반환합니다. 사용자가 목록에서 장소를 선택하면 장소에 대한 정보가 자동 완성 객체에 반환되며 애플리케이션에서 정보를 가져올 수 있습니다. 자세한 내용은 아래를 참고하세요.
그림 1: 자동 완성 텍스트 필드 및 선택 목록그림 2: 완성된 주소 양식
SearchBox는 Autocomplete와 거의 동일한 방식으로 웹페이지에 텍스트 입력란을 추가합니다. 차이점은 다음과 같습니다.
주요 차이는 선택 목록에 표시되는 결과에 있습니다. SearchBox는 확장된 예상 검색어 목록을 제공하며 이 목록에는 Places API에서 정의한 장소 및 추천 검색어가 포함될 수 있습니다. 예를 들어 사용자가 'pizza in new'를 입력하는 경우 선택 목록에 'pizza in New York, NY' 및 다양한 피자 매장 이름이 포함될 수 있습니다.
SearchBox는 Autocomplete보다 적은 검색 제한 옵션을 제공합니다. SearchBox의 경우 지정된 LatLngBounds에 편중하여 검색할 수 있습니다. 자동 완성에서는 특정 국가 및 특정 장소 유형으로 검색을 제한할 수 있으며 경계를 설정할 수도 있습니다. 자세한 내용은 아래를 참고하세요.
그림 3: 검색어와 예상 검색어를 제공하는 SearchBox자세한 내용은 아래를 참고하세요.
AutocompleteService 객체를 만들면 예상 검색어를 프로그래매틱 방식으로 가져올 수 있습니다. getPlacePredictions()를 호출하여 일치하는 장소를 가져오거나 getQueryPredictions()를 호출하여 일치하는 장소와 추천 검색어를 가져올 수 있습니다.
참고: AutocompleteService는 UI 컨트롤을 추가하지 않습니다.
대신 위의 메서드는 예상 검색어 객체의 배열을 반환합니다. 각 예상 검색어 객체에는 예상 검색어의 텍스트 및 참조 정보, 결과가 사용자 입력과 어떻게 일치하는지에 대한 세부정보가 포함됩니다. 자세한 내용은 아래를 참고하세요.
자동 완성 위젯 추가
Autocomplete 위젯은 웹페이지에 텍스트 입력란을 만들고 UI 선택 목록에 장소의 예상 검색어를 제공하고 getPlace() 요청에 대한 응답에 장소 세부정보를 반환합니다. 선택 목록의 각 항목은 Places API에 의해 정의된 단일 장소에 해당합니다.
Autocomplete 생성자는 다음 두 인수를 사용합니다.
text 유형의 HTML input 요소. 자동 완성 서비스가 모니터링하고 결과를 첨부하는 입력란입니다.
사용자가 선택한 PlaceResult의 Place Details 응답에 포함될 데이터
fields의 배열. 속성이 설정되어 있지 않거나 ['ALL']이 전달되는 경우 사용 가능한 모든 필드가 반환되고 청구됩니다(프로덕션 배포의 경우 권장되지 않습니다). 필드의 목록은 PlaceResult를 참고하세요.
지원되는 유형에
나열된 대로 명시적 유형 또는 유형 모음을 지정하는 types의 배열. 유형을 지정하지 않으면 모든 유형이 반환됩니다.
bounds는 장소를 검색할 영역을 지정하는 google.maps.LatLngBounds 객체입니다. 검색 결과는 이 경계 안에 포함된 장소에 편중되지만 이 장소만으로 제한되지는 않습니다.
strictBounds는 API가 지정된 bounds로 정의된 지역 내에 있는 장소만 반환해야 하는지 여부를 지정하는 boolean입니다. API는 결과가 사용자 입력과 일치하더라도 이 지역 외부의 결과를 반환하지 않습니다.
componentRestrictions를 사용하여 결과를 특정 그룹으로 제한할 수 있습니다. 현재 componentRestrictions를 사용하여 최대 5개의 국가로 필터링할 수 있습니다. 국가는 2자리 ISO 3166-1 Alpha-2 호환 국가 코드로 전달해야 합니다. 여러 국가를 하나의 국가 코드 목록으로 전달해야 합니다.
placeIdOnly는 Autocomplete 위젯이 장소 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,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
필요하지 않은 Places Data SKU에 대해 요금이 청구되지 않도록 데이터 필드를 지정하세요. 이전 예에 표시된 대로 위젯 생성자에 전달되는 AutocompleteOptions에 fields 속성을 포함하거나 기존 Autocomplete 객체에서 setFields()를 호출하세요.
기본적으로 사용자가 장소를 선택하면 자동 완성이 선택된 장소의 사용 가능한 모든 데이터 필드를 반환하며 그에 따라 요금이 청구됩니다.
반환할 장소 데이터 필드를 지정하려면 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는 확장된 예상 검색어 목록을 제공하며 이 목록에는 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);
});
프로그래매틱 방식으로 예상 검색어를 가져오려면 AutocompleteService 클래스를 사용하세요. AutocompleteService는 UI 컨트롤을 추가하지 않습니다. 대신 예상 검색어 객체의 배열을 반환합니다. 각 예상 검색어 객체에는 예상 검색어 텍스트, 참조 정보 및 결과가 사용자 입력과 어떻게 일치하는지에 대한 세부정보가 포함됩니다.
이 방법은 위에서 설명한 Autocomplete 및 SearchBox에서 제공하는 것보다 상세하게 사용자 인터페이스를 관리하고자 하는 경우에 유용합니다.
AutocompleteService는 다음 메서드를 제공합니다.
getPlacePredictions()는 장소 예상 검색어를 반환합니다.
참고: '장소'는 Places API에 정의된 것처럼 시설, 지리적 위치 또는 유명한 관심 장소가 될 수 있습니다.
getQueryPredictions()는 확장된 예상 검색어 목록을 반환하며 이 목록에는 Places API에서 정의한 장소 및 추천 검색어가 포함될 수 있습니다. 예를 들어 사용자가 'pizza in new'를 입력하는 경우 선택 목록에 'pizza in New York, NY' 문구 및 다양한 피자 매장 이름이 포함될 수 있습니다.
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;
// 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;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<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 script 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);
새 세션마다 고유한 세션 토큰을 전달해야 합니다. 두 개 이상의 세션에 동일한 토큰을 사용하면 각 요청에 대해 개별적으로 요금이 청구됩니다.
기본적으로 Autocomplete 및 SearchBox에서 제공하는 UI 요소는 Google 지도에 포함되도록 스타일이 지정됩니다. 자신의 사이트에 맞게 스타일링을 조정할 수도 있습니다. 다음과 같은 CSS 클래스를 사용할 수 있습니다. 아래에 나열된 모든 클래스는 Autocomplete 및 SearchBox 위젯에 모두 적용됩니다.
자동 완성 및 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의 나머지 텍스트에 부분적으로 포함될 수 있습니다.
장소 선택 도구 구성요소 사용
참고: 이 샘플에서는 오픈소스 라이브러리를 사용합니다. 라이브러리와 관련된 지원 및 의견은 리드미를 참고하세요.
웹 구성요소를 사용해 봅니다. 장소 선택 도구 웹 구성요소를 사용하면 최종 사용자가 자동 완성을 통해 특정 주소나 장소를 검색할 수 있는 텍스트 입력 기능을 사용할 수 있습니다.
그림 1: 텍스트를 입력하면 자동 완성을 통해 특정 주소나 장소가 검색되는 모습
Place Autocomplete 최적화
이 섹션에서는 Place Autocomplete 서비스를 최대한 활용하는 데 도움이 되는 권장사항을 설명합니다.
다음은 일반 가이드라인입니다.
작동하는 사용자 인터페이스를 개발하는 가장 빠른 방법은 Maps JavaScript API 자동 완성 위젯, Android용 Places SDK 자동 완성 위젯 또는 iOS용 Places SDK 자동 완성 UI 컨트롤을 사용하는 것입니다.
위치 상세 검색 및 위치 제한 필드는 선택사항이지만 자동 완성 성능에 상당한 영향을 미칠 수 있습니다.
API가 오류를 반환하는 경우 오류 처리를 사용하여 앱의 성능이 적절히 저하되도록 합니다.
선택된 항목이 없을 때 앱에서 처리하고 사용자에게 계속할 수 있는 방법을 제공하도록 합니다.
비용 최적화 권장사항
기본 비용 최적화
Place Autocomplete 서비스 사용 비용을 최적화하려면 장소 세부정보 및 Place Autocomplete 위젯에서 필드 마스크를 사용하여 필요한 장소 데이터 필드만 반환하세요.
고급 비용 최적화
요청당 가격에 액세스하고 장소 세부정보 대신 선택된 장소에 대한 Geocoding API 결과를 요청하려면 Place Autocomplete를 프로그래매틱 방식으로 구현해 보세요. Geocoding API와 연결된 요청당 가격은 다음 두 조건이 모두 충족되는 경우 세션당(세션 기반) 가격보다 비용 효과적입니다.
사용자가 선택한 장소의 위도/경도 또는 주소만 필요한 경우 Geocoding API는 장소 세부정보 호출보다 낮은 비용으로 이 정보를 제공합니다.
사용자가 평균 네 개 이하의 자동 완성 예상 검색어 요청 내에서 자동 완성 예상 검색어를 선택하면 요청당 가격이 세션당 가격보다 비용 효과적일 수 있습니다.
요구에 맞는 Place Autocomplete 구현을 선택하는 데 도움이 필요하면 다음 질문에 대한 답변에 해당하는 탭을 선택하세요.
다음 가이드라인에서는 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'처럼 도로 구간 접두사가 있는 주소를 입력하는 경우
