모든 준비를 마쳤습니다!

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

Google Maps JavaScript API 활성화

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

  1. 프로젝트 생성 또는 선택
  2. Google Maps JavaScript API 및 관련 서비스 활성화
  3. 적합한 키 생성
계속

장소 라이브러리

개요

Google Places JavaScript 라이브러리의 함수를 사용하면 애플리케이션이 지도의 경계나 고정된 지점 주변 등의 정의된 영역에 포함된 (이 API에서 시설, 지리적 위치, 또는 유명한 관심 지점으로 정의된) 장소를 검색할 수 있습니다.

Google Places API는 자동완성 기능을 제공하며, 이를 통해 애플리케이션에 Google 지도 검색 필드의 입력 자동완성 검색 기능을 적용할 수 있습니다. 사용자가 주소 입력을 시작하면 자동완성이 나머지를 채웁니다. 자세한 내용은 자동완성 문서를 참조하세요.

시작하기

Google Maps JavaScript API에서 장소 라이브러리를 사용하려면 먼저 Google Maps JavaScript API에 대해 설정한 동일한 프로젝트의 Google API Console에서 Google Places API Web Service를 활성화해야 합니다.

활성화된 API 목록을 보려면:

  1. Google API Console로 이동합니다.
  2. Select a project 버튼을 클릭한 다음 Google Maps JavaScript API에 대해 설정한 동일한 프로젝트를 선택하고 Open을 클릭합니다.
  3. Dashboard의 API 목록에서 Google Places API Web Service를 찾습니다.
  4. 목록에 API가 표시되면 모두 완벽한 상태입니다. API가 표시되지 않으면 활성화합니다.
    1. 페이지 상단에서 ENABLE API를 선택하여 Library 탭을 표시합니다. 또는 왼쪽 메뉴에서 Library를 선택합니다.
    2. Google Places API Web Service를 검색한 다음 결과 목록에서 선택합니다.
    3. ENABLE을 선택합니다. 프로세스가 완료되면 Google Places API Web ServiceDashboard의 API 목록에 나타납니다.

라이브러리 로드

장소 서비스는 메인 Maps JavaScript API 코드와는 별개인 자체 포함된 라이브러리입니다. 이 라이브러리에 포함된 기능을 사용하려면 먼저 Maps API 부트스트랩 URL의 libraries 매개변수를 사용하여 로드해야 합니다.

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

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

사용 제한 및 정책

할당량

Google Places API Web Service 및 장소 자동완성은 Google Places API Web Service에 대한 [사용 제한] 문서에 설명된 사용 할당량을 공유합니다. 이 사용 제한은 Google Maps JavaScript API의 장소 라이브러리을 사용하는 경우에도 적용됩니다. 일일 사용량은 클라이언트측 요청과 서버측 요청의 합계로 계산합니다.

정책

Google Maps JavaScript API의 장소 라이브러리는 Google Places API Web Service에 대해 설명한 정책에 따라 사용해야 합니다.

장소 검색

장소 서비스를 사용하여 네 가지 검색을 수행할 수 있습니다.

  • 주변 검색은 사용자의 위치를 기준으로 주변 장소 목록을 반환합니다.
  • 텍스트 검색은 검색 문자열을 기준으로 주변 장소 목록을 반환합니다. 예: "Pizza".
  • 레이더 검색은 지정된 검색 반경에서 대량의 장소 목록을 반환하지만, 주변 검색이나 텍스트 검색보다는 상세함이 떨어집니다.
  • 장소 세부정보 요청은 사용자 리뷰를 비롯하여 특정 장소에 대한 자세한 정보를 반환합니다.

반환되는 정보에는 식당이나 매장, 사무실 등의 시설과 소도시, 도시 등의 주소나 정치적 영역을 나타내는 '지오코드' 결과 및 기타 관심 지점이 포함될 수 있습니다.

주변 검색 요청

주변 검색을 사용하면 키워드나 입력으로 지정된 영역 내 장소를 검색할 수 있습니다. 주변 검색은 언제나 위치를 포함해야 하며, 다음 두 가지 방법 중 하나로 지정할 수 있습니다.

  • LatLngBounds.
  • location 속성(LatLng 객체로 원의 중심 지정)과 미터 단위로 측정된 반경의 조합으로 정의된 원 영역.

장소 주변 검색은 PlacesServicenearbySearch() 메서드 호출로 시작되고, PlaceResult 객체의 배열을 반환합니다. 3.9 버전부터 nearbySearch() 메서드가 search() 메서드를 대체합니다.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

이 메서드는 다음 필드가 포함된 요청을 받습니다.

  • 다음 중 하나:
    • bounds. 사각형 검색 영역을 정의하는 google.maps.LatLngBounds 객체입니다.
    • locationradius. 전자는 google.maps.LatLng 객체를 취하고 후자는 미터 단위로 원의 반경을 나타내는 간단한 정수를 취합니다. 허용되는 최대 반경은 50,000미터입니다. rankBy를 DISTANCE로 설정한 경우 location을 지정해야 하지만 radius 또는 bounds는 지정할 수 없습니다.
  • keyword(선택 항목) — 모든 이용 가능한 필드와 비교할 검색어입니다. 여기에는 이름, 유형, 주소뿐만 아니라 고객 리뷰와 타사 콘텐츠 등이 포함됩니다.
  • minPriceLevelmaxPriceLevel(선택 항목) — 지정된 가격 범위의 장소로 결과를 제한합니다. 유효한 값의 범위는 0(가장 저렴함)부터 4(가장 비쌈)까지입니다.
  • name(선택 항목) — 장소의 이름과 비교할 검색어입니다. 결과는 전달된 name 값이 있는 항목으로 제한됩니다. 나열된 이름 이외에도 추가 이름이 연관되어 있을 수 있습니다. API는 전달된 name 값을 이러한 모든 이름과 비교합니다. 따라서 등록된 이름이 검색어와 일치하지 않지만 연관된 이름이 일치하는 장소가 결과에서 반환될 수 있습니다.
  • opennow(선택 항목) — 부울 값으로, 장소 서비스가 쿼리 전송 시에 영업 중인 장소만 반환함을 나타냅니다. 이 매개변수를 쿼리에 포함하는 경우, Google Places 데이터베이스에 개점 시간을 지정하지 않은 장소는 반환되지 않습니다. openNowfalse로 설정해도 영향을 미치지 않습니다.
  • rankBy(선택 항목) — 결과가 표시되는 순서를 지정합니다. 가능한 값은 다음과 같습니다.
    • google.maps.places.RankBy.PROMINENCE (기본값). 이 옵션은 유명도에 따라 결과를 정렬합니다. 일치하지만 유명도가 낮은 주변 장소에 설정된 반경 내 유명도가 높은 장소에 높은 순위가 부여됩니다. 유명도는 Google 색인에서 장소 순위, 전체 인기도 및 기타 요인의 영향을 받을 수 있습니다. google.maps.places.RankBy.PROMINENCE가 지정되면 radius 매개변수가 필요합니다.
    • google.maps.places.RankBy.DISTANCE. 이 옵션을 사용하면 특정 location으로부터의 거리를 기준으로 결과가 오름차순으로 정렬됩니다(필수). RankBy.DISTANCE를 지정한 경우 사용자 지정 bounds 및/또는 radius를 지정할 수 없습니다. RankBy.DISTANCE를 지정한 경우 keyword, nametype 중에 하나 이상이 필요합니다.
  • type — 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다. (유형을 두 개 이상 제공하면 첫 번째 항목 이후의 모든 유형은 무시됩니다.) 지원 유형 목록을 참조하세요.
  • types (지원 중단) — 지원 유형이 한 개 이상 포함된 배열입니다. 이 서비스는 지정된 유형 집합에 대한 최상의 결과 집합을 반환합니다.

콜백 메서드를 nearbySearch()에 전달하고, 결과 객체와 google.maps.places.PlacesServiceStatus 응답도 처리해야 합니다.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    types: ['store']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

예시 보기(place-search.html)

텍스트 검색 요청

Google Places 텍스트 검색 서비스는 '뉴욕의 피자 가게' 또는 '오타와 주변의 신발 가게'와 같이 문자열에 기반하여 장소 그룹에 대한 정보를 반환하는 웹 서비스입니다. 이 서비스는 설정된 텍스트 문자열 및 모든 위치 편중과 일치하는 장소 목록을 반환합니다. 검색 응답에는 장소 목록이 포함됩니다. 장소 세부정보 요청을 전송하면 응답에서 모든 장소에 관한 세부정보를 확인할 수 있습니다.

텍스트 검색은 PlacesServicetextSearch() 메서드 호출로 시작됩니다.

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

이 메서드는 다음 필드가 포함된 요청을 받습니다.

  • query(필수) 검색할 텍스트 문자열(예: '레스토랑'). 장소 서비스는 이 문자열을 기준으로 일치 가능성이 높은 항목을 반환하고, 감지된 관련성을 기준으로 검색 결과를 정렬합니다. 검색 요청에서 type 매개변수도 사용할 경우 이 매개변수는 선택 항목이 됩니다.
  • 선택 항목:
    • opennow(선택 항목) — 부울 값으로, 장소 서비스가 쿼리 전송 시에 영업 중인 장소만 반환함을 나타냅니다. 이 매개변수를 쿼리에 포함하는 경우, Google Places 데이터베이스에 개점 시간을 지정하지 않은 장소는 반환되지 않습니다. openNowfalse로 설정해도 영향을 미치지 않습니다.
    • minPriceLevelmaxPriceLevel — 지정된 가격 수준의 장소로 결과를 제한합니다. 유효한 값의 범위는 0(가장 저렴함)부터 4(가장 비쌈)까지입니다.
    • 다음 중 하나:
      • bounds — 검색할 사각형을 지정하는 google.maps.LatLngBounds 객체.
      • locationradiuslocationradius 매개변수를 전달하여 지정한 원 내로 결과를 편중할 수 있습니다. 이렇게 하면 장소 서비스에서 원 내의 결과를 우선적으로 표시하도록 지시합니다. 하지만 여전히 정의한 영역을 벗어난 결과가 표시될 수도 있습니다. location은 google.maps.LatLng 객체를 취하고 radius는 미터 단위로 원의 반경을 나타내는 간단한 정수를 취합니다. 허용되는 최대 반경은 50,000미터입니다.
    • type — 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다. (유형을 두 개 이상 제공하면 첫 번째 항목 이후의 모든 유형은 무시됩니다.) 지원 유형 목록을 참조하세요.
    • types (지원 중단) — 지원 유형이 한 개 이상 포함된 배열입니다. 이 서비스는 지정된 유형 중 하나라도 일치하는 결과를 반환합니다.

콜백 메서드를 textSearch()에 전달하고, 결과 객체와 google.maps.places.PlacesServiceStatus 응답도 처리해야 합니다.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

레이더 검색 요청

레이더 검색을 사용하면 키워드, 유형 또는 이름으로 지정된 검색 반경 내 장소를 검색할 수 있습니다. 레이더 검색은 주변 검색이나 텍스트 검색보다는 더 많은 결과를 반환하지만, 결과에는 필드가 더 적게 포함됩니다. PlacesService.getDetails()을 호출하여 응답에서 장소에 대한 자세한 정보를 얻을 수 있습니다.

radarSearch()가 반환하는 PlaceResult 객체는 다음 속성만 포함합니다.

  • geometry.location
  • place_id
  • reference(참고: reference는 이 페이지의 지원 중단 고지에 설명된 것처럼 이제 지원이 중단되고 place_id로 대체됩니다.)

장소 레이더 검색은 PlacesServiceradarSearch() 메서드 호출로 시작되고, 최대 200개의 PlaceResult 객체 배열을 반환합니다.

service = new google.maps.places.PlacesService(map);
service.radarSearch(request, callback);

이 메서드는 다음 필드가 포함된 요청을 받습니다.

  • 다음 중 하나:
    • bounds. 사각형 검색 영역을 정의하는 google.maps.LatLngBounds 객체입니다.
    • locationradius. 전자는 google.maps.LatLng 객체를 취하고 후자는 미터 단위로 원의 반경을 나타내는 간단한 정수를 취합니다. 허용되는 최대 반경은 50,000미터입니다.
  • 다음 중 하나 이상:
    • keyword(선택항목) — 모든 이용 가능한 필드와 비교할 검색어입니다. 여기에는 이름, 유형, 주소뿐만 아니라 고객 리뷰와 타사 콘텐츠 등이 포함되어 있습니다.
    • name(선택항목) — 장소의 이름과 비교할 검색어입니다. 결과는 전달된 name 값이 있는 항목으로 제한됩니다. 나열된 이름 이외에도 추가 이름이 연관되어 있을 수 있습니다. API는 전달된 name 값을 이러한 모든 이름과 비교합니다. 따라서 등록된 이름이 검색어와 일치하지 않지만 연관된 이름이 일치하는 장소가 결과에서 반환될 수 있습니다.
    • type — 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다. (유형을 두 개 이상 제공하면 첫 번째 항목 이후의 모든 유형은 무시됩니다.) 지원 유형 목록을 참조하세요.
    • types (지원 중단) — 지원 유형이 한 개 이상 포함된 배열입니다. 이 서비스는 지정된 유형 집합에 대한 최상의 결과 집합을 반환합니다.
  • 선택 항목:
    • minPriceLevelmaxPriceLevel(선택 항목) — 지정된 가격 수준의 장소로 결과를 제한합니다. 유효 값은 0(가장 저렴함)부터 4(가장 비쌈)의 범위로 표시됩니다.
    • openNow — 부울 값. 쿼리 전송 시에 영업 중인 장소만 반환하는 장소 서비스를 나타냅니다. 이 매개변수를 쿼리에 포함하는 경우, Google Places 데이터베이스에 개점 시간을 지정하지 않은 장소는 반환되지 않습니다. openNowfalse로 설정해도 영향을 미치지 않습니다.

콜백 메서드를 radarSearch()에 전달하고, PlaceResults 객체와 google.maps.places.PlacesServiceStatus도 처리해야 합니다.

// 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">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

  infoWindow = new google.maps.InfoWindow();
  service = new google.maps.places.PlacesService(map);

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'https://developers.google.com/maps/documentation/javascript/images/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}
<div id="map"></div>
/* 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;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap&libraries=places,visualization" async defer></script>
// 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">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

  infoWindow = new google.maps.InfoWindow();
  service = new google.maps.places.PlacesService(map);

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'https://developers.google.com/maps/documentation/javascript/images/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

예시 보기(place-radar-search.html).

검색 응답

상태 코드

PlacesServiceStatus 응답 객체는 요청의 상태를 포함합니다. 또한 장소 요청이 실패한 원인을 추적하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. 가능한 상태 값은 다음과 같습니다.

  • ERROR: Google 서버 접속 중 문제가 발생했습니다.
  • INVALID_REQUEST: 이 요청이 잘못되었습니다.
  • OK: 응답에 유효한 결과가 포함되어 있습니다.
  • OVER_QUERY_LIMIT: 웹페이지가 요청 할당량을 초과했습니다.
  • REQUEST_DENIED: 이 웹페이지는 PlacesService를 사용할 수 없습니다.
  • UNKNOWN_ERROR: 서버 오류로 인해 PlacesService 요청을 처리할 수 없습니다. 다시 시도하면 요청이 성공할 수도 있습니다.
  • ZERO_RESULTS: 이 요청에 대해 결과를 찾지 못했습니다.

장소 검색 결과

nearbySearch()textSearch() 함수는 PlaceResult 객체의 배열을 반환합니다. radarSearch() 함수는 에 설명된 것처럼 PlaceResult에서 필드의 하위 집합을 반환합니다.

PlaceResult 객체는 다음 속성을 포함할 수 있습니다.

  • formatted_address는 이 장소의 사람이 읽을 수 있는 주소가 포함된 문자열입니다. 이 주소는 대개 "우편 주소"와 일치합니다. formatted_address 속성은 텍스트 검색에 대해서만 반환됩니다.
  • geometry: 장소의 지리 관련 정보. 다음 항목이 포함됩니다.
    • location은 장소의 위도와 경도를 제공합니다.
    • viewport는 해당 장소를 볼 때 지도에서 선호하는 뷰포트를 정의합니다.
  • html_attributions: 검색 결과를 표시할 때 표시해야 하는 특성 배열. 배열의 각 항목은 단일 특성에 대한 HTML 텍스트를 포함합니다. 참고: 이는 전체 검색 응답에 대한 모든 특성의 집계입니다. 따라서 응답의 모든 PlaceResult 객체는 동일한 특성 목록을 포함합니다.
  • icon: 해당 장소 유형을 나타내는 데 사용할 수 있는 이미지 리소스에 대한 URL.
  • id: 이 장소를 표시하는 고유 식별자를 포함합니다. 이 식별자는 이 장소에 대한 정보를 검색하는 데 사용할 수 없지만, 장소에 관한 데이터를 통합하고 별도의 검색을 통해 장소의 ID를 확인하는 데 사용할 수 있습니다. ID는 가끔 변경될 수 있습니다. 따라서 저장된 장소의 ID는 같은 장소의 차후 세부정보 요청에서 반환된 ID와 비교하여 필요한 경우 업데이트할 것을 권장합니다. 참고: id는 이 페이지의 지원 중단 고지에서 설명하였듯이 이제 지원이 중단되고 place_id로 대체됩니다.
  • name: 장소 이름.
  • opening_hours는 다음 정보를 포함할 수 있습니다.
    • open-now는 장소가 현재 영업 중임을 나타내는 부울 값입니다.
  • place_id는 장소를 고유하게 식별하는 텍스트 식별자입니다. 장소에 관한 정보를 검색하려면 이 식별자를 장소 세부정보 요청placeId 필드에 삽입해 전달합니다. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.
  • rating은 장소의 평점을 포함합니다(사용자 리뷰 기준으로 0.0~5.0).
  • reference는 향후 세부정보 서비스를 검색하는 데 사용할 수 있는 토큰을 포함합니다. 이 토큰은 세부정보 서비스에 대한 요청에 사용된 참조와 다를 수 있습니다. 장소에 대해 저장된 참조는 정기적으로 업데이트하는 것이 좋습니다. 토큰은 장소를 고유하게 식별하지만 장소는 토큰을 식별하지 못합니다. 한 장소에 다수의 유효한 참조 토큰이 있을 수 있습니다. 참고: reference는 이 페이지의 지원 중단 고지에서 설명하였듯이 이제 지원이 중단되고 place_id로 대체됩니다.
  • types 이 장소에 대한 유형의 배열입니다(예: ["political", "locality"] 또는 ["restaurant", "lodging"]).
  • vicinity: 거리 이름, 번지, 지역을 비롯하여 장소의 단순화된 주소를 나열하지만 시/도, 우편 번호 또는 국가를 나열하지는 않습니다. 예를 들어, Google 호주 시드니 사무실의 vicinity 값은 5/48 Pirrama Road, Pyrmont입니다.

추가 결과 액세스

기본적으로 각 장소 검색은 쿼리당 최대 20개 결과를 반환합니다. 하지만 각 검색은 세 페이지에 걸쳐 최대 60개까지의 결과를 반환할 수 있습니다. 추가 페이지는 PlaceSearchPagination 객체를 통해 이용할 수 있습니다. 초가 페이지에 액세스하려면 콜백 함수를 통해 PlaceSearchPagination 객체를 캡처해야 합니다. PlaceSearchPagination 객체는 다음과 같이 정의됩니다.

  • hasNextPage는 부울 속성으로, 추가 검색 결과가 있는지 나타냅니다. true이면 추가 검색 결과가 있다는 뜻입니다.
  • nextPage()는 다음 검색 집합을 반환하는 함수입니다. 검색을 실행한 후에 다음 결과 페이지를 사용하려면 2초를 기다려야 합니다.

다음 검색 집합을 보려면 nextPage를 호출합니다. 각 결과 페이지는 다음 결과 페이지를 표시하기 전에 표시되어야 합니다. 각 검색은 사용 제한 계산 시 단일 요청으로 계산됩니다.

아래 예시는 콜백 함수를 변경하여 PlaceSearchPagination 객체를 캡처하고 여러 검색 요청을 시행하는 방법을 설명합니다.

// 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">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

  map = new google.maps.Map(document.getElementById('map'), {
    center: pyrmont,
    zoom: 17
  });

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      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)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}
<div id="map"></div>
<div id="right-panel">
  <h2>Results</h2>
  <ul id="places"></ul>
  <button id="more">More results</button>
</div>
/* 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;
}
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
#right-panel {
  font-family: Arial, Helvetica, sans-serif;
  position: absolute;
  right: 5px;
  top: 60%;
  margin-top: -195px;
  height: 330px;
  width: 200px;
  padding: 5px;
  z-index: 5;
  border: 1px solid #999;
  background: #fff;
}
h2 {
  font-size: 22px;
  margin: 0 0 5px 0;
}
ul {
  list-style-type: none;
  padding: 0;
  margin: 0;
  height: 271px;
  width: 200px;
  overflow-y: scroll;
}
li {
  background-color: #f1f1f1;
  padding: 10px;
  text-overflow: ellipsis;
  white-space: nowrap;
  overflow: hidden;
}
li:nth-child(odd) {
  background-color: #fcfcfc;
}
#more {
  width: 100%;
  margin: 5px 0 0 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initMap" async defer></script>
// 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">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

  map = new google.maps.Map(document.getElementById('map'), {
    center: pyrmont,
    zoom: 17
  });

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      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)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

예시 보기(place-search-pagination.html).

장소 세부정보

장소 서비스는 영역 내의 장소 목록을 제공하는 이외에도 특정 장소에 대한 상세한 정보를 반환할 수도 있습니다. 장소 검색 응답에서 장소가 반환된 후에, 장소 ID를 사용하여 전체 주소, 전화번호, 사용자 평점, 리뷰 등의 자세한 추가 정보를 요청할 수 있습니다. (장소 참조를 사용하여 장소 세부정보를 검색할 수도 있지만, 이 필드는 이 페이지의 지원 중단 고지에 설명된 것처럼 지원이 중단되고 장소 ID로 대체됩니다.)

장소 세부정보 요청

장소 세부정보는 서비스의 getDetails() 메서드를 호출하여 요청합니다.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

이 메서드는 원하는 장소의 placeId 또는 reference가 포함된 요청을 받습니다. reference는 이 페이지의 지원 중단 고지에 설명된 것처럼 이제 지원이 중단되고 placeId로 대체됩니다. 장소 ID를 포함하는 장소를 참조하는 방법에 대해 자세히 알아보세요.

또한 콜백 메서드도 취합니다. 이 콜백 메서드는 google.maps.places.PlacesServiceStatus 응답과 google.maps.places.PlaceResult 객체에 전달된 상태 코드를 처리해야 합니다.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

예시 보기(place-details.html)

장소 세부정보 응답

상태 코드

PlacesServiceStatus 응답 객체는 요청의 상태를 포함합니다. 또한 장소 세부정보 요청이 실패한 원인을 추적하는 데 도움이 되는 디버깅 정보를 포함할 수 있습니다. 가능한 상태 값은 다음과 같습니다.

  • ERROR: Google 서버 접속 중 문제가 발생했습니다.
  • INVALID_REQUEST: 이 요청이 잘못되었습니다.
  • OK: 응답에 유효한 결과가 포함되어 있습니다.
  • OVER_QUERY_LIMIT: 웹페이지가 요청 할당량을 초과하였습니다.
  • NOT_FOUND 지역정보 데이터베이스에서 참조 위치를 찾을 수 없습니다.
  • REQUEST_DENIED: 이 웹페이지는 PlacesService를 사용할 수 없습니다.
  • UNKNOWN_ERROR: 서버 오류로 인해 PlacesService 요청을 처리할 수 없습니다. 다시 시도하면 요청이 성공할 수도 있습니다.
  • ZERO_RESULTS: 이 요청에서 결과를 찾지 못했습니다.

장소 세부정보 결과

getDetails() 호출에 성공하면 다음 속성을 포함한 PlaceResult 객체를 반환합니다.

  • address_components: 이 장소의 위치에 대한 주소 구성 요소 컬렉션. 자세한 내용은 지오코딩 서비스의 주소 구성 요소 유형 섹션을 참조하세요.
  • formatted_address: 장소의 전체 주소.
  • formatted_phone_number: 장소의 전화번호. 번호의 지역 변환에 따라 형식을 지정합니다.
  • geometry: 장소의 지리 관련 정보. 다음 항목이 포함됩니다.
    • location은 장소의 위도와 경도를 제공합니다.
    • viewport는 해당 장소를 볼 때 지도에서 선호하는 뷰포트를 정의합니다.
  • html_attributions: 이 장소 결과에 대해 표시할 특성 텍스트.
  • icon: 해당 장소 유형을 나타내는 데 사용할 수 있는 이미지 리소스에 대한 URL.
  • id: 이 장소를 표시하는 고유 식별자를 포함합니다. 이 식별자는 이 장소에 대한 정보를 검색하는 데 사용할 수 없지만, 장소에 관한 데이터를 통합하고 별도의 검색을 통해 장소의 ID를 확인하는 데 사용할 수 있습니다. ID는 가끔 변경될 수 있습니다. 따라서 저장된 장소의 ID는 같은 장소의 차후 세부정보 요청에서 반환된 ID와 비교하여 필요한 경우 업데이트할 것을 권장합니다. 참고: id는 이 페이지의 지원 중단 고지에서 설명하였듯이 이제 지원이 중단되고 place_id로 대체됩니다.
  • international_phone_number에는 장소의 전화번호가 국제 형식으로 포함됩니다. 국제 형식에는 국가 코드가 포함되며 플러스(+) 부호가 접두사로 붙습니다. 예를 들어, Google 호주 시드니 지사의 international_phone_number+61 2 9374 4000입니다.
  • name: 장소 이름.
  • utc_offset은 장소의 현재 시간대가 UTC와 얼마나 차이가 나는지 분 단위로 보여주는 정보를 포함합니다. 예를 들어, 서머타임 기간 동안 호주 시드니에 위치한 장소의 값은 660(UTC에서 +11시간)이며, 서머타임을 벗어난 캘리포니아에 있는 장소의 값은 -480(UTC에서 -8시간)이 됩니다.
  • opening_hours는 다음 정보를 포함합니다.
    • open-now는 장소가 현재 영업 중임을 나타내는 부울 값입니다.
    • periods[]는 7일 단위의 영업 기간 배열로, 일요일부터 시작하여 순서대로 지정됩니다. 각 기간에는 다음과 같은 항목이 포함됩니다.
      • open은 장소의 영업 시작 시간을 나타내는 요일 및 시간 객체의 쌍을 포함합니다.
        • day는 일요일부터 시작하여 각 요일에 해당하는 0~6까지의 숫자를 포함합니다. 예를 들어, 2는 화요일을 의미합니다.
        • time은 24시간 hhmm 형식의 시간을 포함할 수 있습니다(값의 범위는 0000~2359입니다). time은 해당 장소의 시간대로 표시됩니다.
      • close는 장소의 영업 종료 시간을 나타내는 요일 및 시간 객체의 쌍을 포함합니다. 참고: 장소가 항시 열려 있으면, close 섹션은 응답에서 누락됩니다. 애플리케이션은 open 기간의 day 값이 0이고 time 값이 0000이고 close 값이 없으면, 항시 열려 있다고 신뢰할 수 있습니다.
    • weekday_text는 각 요일의 지정된 개점 시간을 나타내는 7개의 문자열 배열입니다. 장소 세부정보 요청에 language 매개변수가 지정된 경우, 장소 서비스는 해당 언어에 맞게 개점 시간을 적절히 구성하고 현지화합니다. 이 배열에서 요소의 순서는 language 매개변수에 따라 다릅니다. 일부 언어는 월요일에 한 주를 시작하고 다른 언어는 일요일에 시작합니다.
  • permanently_closed: 장소가 영구적으로 폐점되었는지 여부를 나타내는 부울 플래그(true 값). 장소가 영구적으로 폐점되지 않은 경우 이 플래그는 응답에서 제외됩니다.
  • photos[]: PlacePhoto 객체의 배열. PlacePhotogetUrl() 메서드로 사진을 얻거나 다음 값에 대해 객체를 검사하는 데 사용할 수 있습니다.
    • height: 픽셀 단위의 이미지의 최대 높이.
    • width: 픽셀 단위의 이미지의 최대 너비.
    • html_attributions: 이 장소 사진에 표시할 특성 텍스트.
  • place_id: 장소를 고유하게 식별하고 장소 세부정보 요청을 통해 장소 정보를 검색하는 데 사용할 수 있는 텍스트 식별자. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.
  • rating: 장소의 평점(집계된 사용자 리뷰 기준으로 0.0~5.0).
  • reference는 향후 세부정보 서비스를 검색하는 데 사용할 수 있는 토큰을 포함합니다. 이 토큰은 세부정보 서비스에 대한 요청에 사용된 참조와 다를 수 있습니다. 장소에 대해 저장된 참조는 정기적으로 업데이트하는 것이 좋습니다. 토큰은 장소를 고유하게 식별하지만 장소는 토큰을 식별하지 못합니다. 한 장소에 다수의 유효한 참조 토큰이 있을 수 있습니다. 참고: reference는 이 페이지의 지원 중단 고지에서 설명하였듯이 이제 지원이 중단되고 place_id로 대체됩니다.
  • reviews는 최대 5개의 리뷰로 구성된 배열입니다. 각 리뷰는 여러 구성 요소로 구성됩니다.
    • aspects[]PlaceAspectRating 객체 배열을 포함하며, 각 객체는 해당 시설의 단일 속성에 대한 평점을 제공합니다. 배열의 첫 번째 객체가 기본 평가항목으로 간주됩니다. 각 PlaceAspectRating은 다음과 같이 정의됩니다.
      • type은 평점을 받는 평가항목의 이름입니다. 다음 유형이 지원됩니다: appeal, atmosphere, decor, facilities, food, overall, qualityservice.
      • rating은 특정 평가항목에 대한 사용자 평점입니다(0~3).
    • author_name은 리뷰를 제출한 사용자의 이름입니다. 익명 리뷰는 "Google 사용자"로 특성화됩니다. 언어 매개변수가 설정된 경우, "Google 사용자"문구는 현지화된 문자열을 반환합니다.
    • author_url은 사용자 Google+ 프로필의 URL입니다(있는 경우).
    • language는 사용자 리뷰에 사용된 언어를 표시하는 IETF 언어 코드입니다. 이 필드에는 기본 언어 태그만 포함되며, 국가나 지역을 표시하는 보조 태그는 포함되지 않습니다. 예를 들어, 모든 영어 리뷰는 'en'으로만 태그가 지정되며 'en-AU'나 'en-UK'와 같은 태그는 없습니다.
    • rating은 이 장소에 대한 사용자의 전체적 평점입니다. 평점은 1~5 사이의 정수입니다.
    • text는 사용자 리뷰입니다. Google Places에서 위치를 리뷰할 때, 텍스트 리뷰는 선택 항목이므로 비어 있을 수 있습니다.
  • types 이 장소에 대한 유형의 배열입니다(예: ["political", "locality"] 또는 ["restaurant", "lodging"]).
  • url: 이 장소에 대한 공식 Google 페이지의 URL. 이 URL은 해당 장소에 대한 최선의 정보가 포함된 Google 소유 페이지입니다. 애플리케이션에서는 이 장소에 대한 자세한 결과를 사용자에게 표시하는 모든 화면에 이 페이지를 링크하거나 포함해야 합니다.
  • vicinity: 거리 이름, 번지, 지역을 비롯하여 장소의 단순화된 주소를 나열하지만 시/도, 우편 번호 또는 국가를 나열하지는 않습니다. 예를 들어, Google 호주 시드니 사무실의 vicinity 값은 5/48 Pirrama Road, Pyrmont입니다. vicinity 속성은 주변 검색에서만 반환됩니다.
  • website는 사업체의 홈페이지 등 장소의 공식적인 웹사이트를 나열합니다.

일부 위치에서 다차원 평점을 사용하지 못할 수도 있습니다. 리뷰 수가 거의 없는 경우 세부정보 응답에 기존 1.0~5.0의 평점이 포함되거나(있을 경우) 아예 포함되지 않습니다.

장소 ID로 장소 참조

Google 지도의 장소는 장소 ID로 고유하게 참조할 수 있습니다. 장소 ID는 사업체, 랜드마크, 공원 및 교차로를 포함한 대부분의 위치에서 사용할 수 있으며 안정적입니다. 즉, 특정 위치에 대해 장소 ID를 식별한 후에 다음에 해당 위치를 찾을 때 이 값을 재사용할 수 있습니다.

앱에서 장소 ID를 사용하려면 ID를 조회해야 합니다. 장소 ID는 장소 검색의 PlaceResult나 이나 세부장소 요청에서 확인할 수 있습니다. 나중에 이 장소 ID를 사용하여 장소 세부정보를 찾거나 로그인한 지도에서 특성 저장 을 활성화할 수 있습니다.

장소 ID는 Google Maps API 서비스 약관의 10.5.d 조항에 명시된 캐싱 제한에서 제외됩니다. 따라서 장소 ID 값을 무제한으로 저장할 수 있습니다.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

장소 사진

장소 사진 기능을 사용하면 고품질의 사진 콘텐츠를 사이트에 쉽게 추가할 수 있습니다. 사진 서비스를 사용하면 장소 및 Google+ 로컬 데이터베이스에 저장된 수백만 개의 사진에 액세스할 수 있습니다. 장소 검색이나 장소 세부정보 요청을 통해 장소를 검색하면, 관련 사진 콘텐츠에 대해 사진 참조가 반환됩니다. 주변 검색 및 텍스트 검색 요청 또한 장소별로 단일 사진 참조를 반환합니다(연관된 경우). 사진 서비스를 사용하면 참조 사진에 액세스하고 애플리케이션에 맞게 최적의 크기로 이미지를 조정할 수 있습니다.

PlacePhoto 객체의 배열이 PlacesService에 대한 모든 getDetails(), textSearch() 또는 nearbySearch() 요청에서 PlaceResult 객체의 일부로 반환됩니다.

참고: 반환되는 사진 수는 요청에 따라 다릅니다.

  • 주변 검색이나 텍스트 검색은 하나의 PlacePhoto 객체만 반환합니다.
  • 레이더 검색은 사진 정보를 반환하지 않습니다.
  • 세부정보 요청은 최대 10개의 PlacePhoto 객체를 반환합니다.

PlacePhoto.getUrl() 메서드를 호출하고 유효한 PhotoOptions 객체를 전달하여 관련 이미지의 URL을 요청할 수 있습니다. PhotoOptions 객체를 사용하여 이미지에 원하는 최대 높이와 너비를 지정할 수 있습니다. max_heightmax_width 값을 모두 지정하면 사진 서비스가 두 크기 중에 작은 쪽에 맞춰 이미지 크기를 조정하고, 원래의 가로세로 비율은 그대로 유지합니다.

다음 코드 스니펫은 장소 객체를 받고, 사진이 있는 경우 지도에 마커를 추가합니다. 기본 마커 이미지는 작은 버전의 사진으로 대체됩니다.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({'maxWidth': 35, 'maxHeight': 35})
  });
}

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

Google Maps JavaScript API
Google Maps JavaScript API
도움이 필요하시나요? 지원 페이지를 방문하세요.