장소 라이브러리

개요

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

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

시작하기

Maps JavaScript API 또는 JavaScript에 대해 잘 모르는 경우 시작하기 전에 JavaScript 및 API 키 가져오기에 대해 알아보세요.

API 사용 설정

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

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

  1. Google Cloud 콘솔로 이동합니다.
  2. 프로젝트 선택 버튼을 클릭한 후 Maps JavaScript API를 위해 설정한 것과 동일한 프로젝트를 선택하고 열기를 클릭합니다.
  3. 대시보드의 API 목록에서 Places API를 찾습니다.
  4. 목록에 Places 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&loading=async&libraries=places&callback=initMap">
</script>

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

API 키의 API 제한사항 목록에 Places API 추가

키에 API 제한을 적용하면 API 키 사용이 하나 이상의 API 또는 SDK로 제한됩니다. API 키와 연결된 API 또는 SDK에 대한 요청이 처리됩니다. API 키와 연결되지 않은 API 또는 SDK에 대한 요청은 처리되지 않습니다. Maps JavaScript API의 장소 라이브러리에서 API 키의 사용을 제한하려면 다음 안내를 따르세요.
  1. Google Cloud 콘솔로 이동합니다.
  2. 프로젝트 드롭다운을 클릭하고 보호할 API 키가 포함된 프로젝트를 선택합니다.
  3. 메뉴 버튼 을 클릭하고 Google Maps Platform > 사용자 인증 정보를 선택합니다.
  4. 사용자 인증 정보 페이지에서 보호할 API 키의 이름을 클릭합니다.
  5. API 키 제한 및 이름 바꾸기 페이지에서 제한을 설정합니다.
    • API 제한
      • 키 제한을 선택합니다.
      • API 선택을 클릭하고 Maps JavaScript API와 Places API를 모두 선택합니다.
        (두 API 중 하나가 표시되지 않으면 사용 설정해야 합니다.)
  6. 저장을 클릭합니다.

사용량 한도 및 정책

할당량

장소 라이브러리는 Places API의 사용량 한도 문서에 설명된 대로 Places API와 사용 할당량을 공유합니다.

정책

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

장소 검색

장소 서비스를 사용하여 다음과 같은 검색을 실행할 수 있습니다.

반환되는 정보에는 음식점이나 매장, 사무실과 같은 시설과 주소, 도시와 같은 행정 구역, 기타 관심 장소가 포함된 '지오코드' 결과가 포함될 수 있습니다.

장소 찾기 요청

장소 찾기 요청을 사용하면 텍스트 쿼리 또는 전화번호로 장소를 검색할 수 있습니다. 장소 찾기 요청에는 다음 두 가지 유형이 있습니다.

쿼리에서 장소 찾기

쿼리에서 장소 찾기는 텍스트 입력을 받아 장소를 반환합니다. 업체 이름 또는 주소 등 모든 유형의 장소 데이터를 입력할 수 있습니다. 쿼리에서 장소 찾기를 요청하려면 다음 매개변수를 사용하는 PlacesService의 findPlaceFromQuery() 메서드를 호출하세요.

  • query(필수): 검색할 텍스트 문자열(예: '음식점' 또는 '중앙로 123'). 장소 이름, 주소 또는 시설의 카테고리여야 합니다. 다른 유형의 입력을 사용하면 오류가 발생할 수 있으며 유효한 결과가 반환되지 않을 수 있습니다. Places API는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다.
  • fields(필수): 반환할 장소 데이터 유형을 지정하는 하나 이상의 필드
  • locationBias(선택사항): 검색할 영역을 정의하는 좌표. 다음 중 하나입니다.

또한 findPlaceFromQuery()에 콜백 메서드를 전달하여 결과 객체와 google.maps.places.PlacesServiceStatus 응답을 처리해야 합니다.

다음 예는 'Museum of Modern Art Australia'를 검색하고 name 및 geometry 필드를 포함하는 findPlaceFromQuery() 호출을 보여줍니다.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

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

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

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

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 예 보기

전화번호에서 장소 찾기

전화번호에서 장소 찾기는 전화번호를 입력 받아 장소를 반환합니다. 전화번호에서 장소 찾기를 요청하려면 다음 매개변수를 사용하는 PlacesService의 findPlaceFromPhoneNumber() 메서드를 호출하세요.

  • phoneNumber(필수): E.164 형식의 전화번호
  • fields(필수): 반환할 장소 데이터 유형을 지정하는 하나 이상의 필드
  • locationBias(선택사항): 검색할 영역을 정의하는 좌표. 다음 중 하나입니다.

또한 findPlaceFromPhoneNumber()에 콜백 메서드를 전달하여 결과 객체와 google.maps.places.PlacesServiceStatus 응답을 처리해야 합니다.

필드(장소 찾기 메서드)

fields 매개변수를 사용하여 반환할 장소 데이터 유형의 배열을 지정합니다. 예: fields: ['formatted_address', 'opening_hours', 'geometry']. 복합 값을 지정하려면 점을 사용하세요. 예: opening_hours.weekday_text

필드는 장소 검색결과에 해당하며 기본, 연락처, 분위기 등 세 결제 카테고리로 분류됩니다. 기본 필드에는 기본 요율로 청구되며 추가 요금이 발생하지 않습니다. 연락처 및 분위기 필드에는 더 높은 요율로 청구됩니다. 자세한 내용은 가격표를 참고하세요. 저작자 표시(html_attributions)는 필드 요청 여부에 관계없이 모든 호출에서 항상 반환됩니다.

기본

기본 카테고리에는 다음 필드가 포함됩니다.
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed(지원 중단됨), photos, place_id, plus_code, types

연락처

연락처 카테고리에는 다음 필드가 포함됩니다. opening_hours
(Maps JavaScript API의 장소 라이브러리에서는 지원 중단됨. opening_hours 결과를 얻으려면 장소 세부정보 요청을 사용하세요).

분위기

분위기 카테고리에는 다음 필드가 포함됩니다. price_level, rating, user_ratings_total

findPlaceFromQuery() 및 findPlaceFromPhoneNumber() 메서드는 각각 동일한 필드 집합을 사용하며 각 응답에 동일한 필드를 반환할 수 있습니다.

위치 편중 설정(장소 찾기 메서드)

특정 지역에 편중된 장소 찾기 결과를 얻으려면 locationBias 매개변수를 사용하세요. 다음과 같은 방법으로 locationBias를 설정할 수 있습니다.

특정 지역에 편중된 결과:

locationBias: {lat: 37.402105, lng: -122.081974}

검색할 직사각형 영역 정의:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

LatLngBounds를 사용할 수도 있습니다.

특정 지역을 중심으로 검색할 반지름(미터) 정의:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

주변 검색 요청

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

  • LatLngBounds.
  • 원의 중심을 LatLng 객체로 지정하는 location 속성과 미터 단위로 측정되는 반지름의 조합으로 정의되는 원형 영역

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

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

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

  • 다음 중 하나:
    • bounds: 직사각형 검색 영역을 정의하는 google.maps.LatLngBounds 객체 경계 영역의 최대 지원되는 대각선 거리는 약 100,000미터입니다.
    • location 및 radius. 전자는 google.maps.LatLng 객체를 사용하고 후자는 원의 반지름을 미터 단위로 나타내는 간단한 정수를 사용합니다. 허용되는 최대 반지름은 50,000미터입니다. rankBy가 DISTANCE로 설정된 경우 location을 지정해야 하지만 radius나 bounds는 지정할 수 없습니다.
  • keyword(선택사항) - 사용 가능한 모든 필드와 대조할 용어. 이름, 유형, 고객 리뷰 및 기타 서드 파티 콘텐츠를 포함하되 이에 국한되지 않습니다.
  • minPriceLevel 및 maxPriceLevel(선택사항) - 지정된 범위 내의 장소로만 결과를 제한합니다. 유효한 값의 범위는 0(가장 저렴함)~4(가장 비쌈)입니다.
  • name 지원 중단됨. keyword와 같습니다. 이 필드의 값은 keyword 필드의 값과 결합되어 동일한 검색 문자열의 일부로 전달됩니다.
  • openNow(선택사항) - 장소 서비스에서 쿼리가 전송된 시점에 영업 중인 장소만 반환해야 함을 나타내는 불리언 값. 이 매개변수를 쿼리에 포함하면 Google 지역 정보 데이터베이스에 영업시간을 지정하지 않은 장소는 반환되지 않습니다. openNow를 false로 설정해도 효과가 없습니다.
  • 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, name 또는 type 중 하나 이상이 필요합니다.
  • type - 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다(두 개 이상의 유형을 제공하면 첫 번째 항목 이후의 모든 유형은 무시됩니다). 지원되는 유형의 목록을 참고하세요.

또한 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',
    type: ['restaurant']
  };

  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++) {
      createMarker(results[i]);
    }
  }
}

예 보기

텍스트 검색 요청

Google 지역 정보 텍스트 검색 서비스는 문자열(예: '뉴욕의 피자' 또는 '오타와 근처의 신발 가게')을 기반으로 장소의 집합에 대한 정보를 반환하는 웹 서비스입니다. 이 서비스는 사전에 설정된 텍스트 문자열 및 특정 위치와 일치하는 장소의 목록을 반환합니다. 검색 응답에는 장소의 목록이 포함됩니다. 응답에 포함된 장소에 대한 자세한 내용을 확인하려면 장소 세부정보 요청을 전송하세요.

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

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

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

  • query(필수): 검색할 텍스트 문자열(예: ;음식점' 또는 '중앙로 123'). 장소 이름, 주소 또는 시설의 카테고리여야 합니다. 다른 유형의 입력을 사용하면 오류가 발생할 수 있으며 유효한 결과가 반환되지 않을 수 있습니다. 장소 서비스는 이 문자열을 기반으로 일치 가능성이 있는 항목을 반환하고 감지된 관련성을 기반으로 검색 결과를 정렬합니다. type 매개변수도 검색 요청에 사용되는 경우 이 매개변수는 선택사항입니다.
  • 선택 항목:
    • openNow - 장소 서비스에서 쿼리가 전송된 시점에 영업 중인 장소만 반환해야 함을 나타내는 불리언 값. 이 매개변수를 쿼리에 포함하면 Google 지역 정보 데이터베이스에 영업시간을 지정하지 않은 장소는 반환되지 않습니다. openNow를 false로 설정해도 효과가 없습니다.
    • minPriceLevel 및 maxPriceLevel - 지정된 범위 내의 장소로만 결과를 제한합니다. 유효한 값의 범위는 0(가장 저렴함)~4(가장 비쌈)입니다.
    • 다음 중 하나:
      • bounds: 직사각형 검색 영역을 정의하는 google.maps.LatLngBounds 객체여야 합니다. 경계 영역의 최대 지원되는 대각선 거리는 약 100,000미터입니다.
      • location 및 radius — location 및 radius 매개변수를 전달하여 특정 원에 편중된 결과를 얻을 수 있습니다. 이 매개변수를 사용하면 장소 서비스에서 해당 원 내의 결과를 우선적으로 표시합니다. 정의된 영역 밖의 결과가 표시될 수도 있습니다. location은 google.maps.LatLng 객체를 사용하고 radius는 원의 반경을 미터 단위로 나타내는 간단한 정수를 사용합니다. 허용되는 최대 반경은 50,000미터입니다.
    • type - 지정된 유형과 일치하는 장소로 결과를 제한합니다. 하나의 유형만 지정할 수 있습니다(두 개 이상의 유형을 제공하면 첫 번째 항목 이후의 모든 유형은 무시됩니다). 지원되는 유형의 목록을 참고하세요.

또한 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]);
    }
  }
}

검색 응답

상태 코드

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

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

장소 검색 결과

findPlace(), nearbySearch(), textSearch() 함수는 PlaceResult 객체의 배열을 반환합니다.

각 PlaceResult 객체에는 다음과 같은 속성이 포함될 수도 있습니다.

  • business_status는 장소가 비즈니스인 경우 장소의 영업 상태를 나타냅니다. 다음 값 중 하나가 포함될 수 있습니다.
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    데이터가 없으면 business_status가 반환되지 않습니다.
  • formatted_address는 이 장소의 인간이 읽을 수 있는 주소가 포함된 문자열입니다. formatted_address 속성은 텍스트 검색의 경우에만 반환됩니다.

    이 주소는 대개 우편 주소와 일치합니다. 참고: 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 우편 주소의 배포가 허용되지 않습니다.

    형식이 지정된 주소는 하나 이상의 주소 구성요소로 논리적으로 구성됩니다. 예를 들어 주소 '111 8th Avenue, New York, NY'는 '111'(번지), '8th Avenue'(경로), 'New York'(도시) 및 'NY'(미국의 주)로 구성됩니다.

    형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요. 대신 API 응답에 형식이 지정된 주소 필드 외에 포함되는 개별 주소 구성요소를 사용해야 합니다.

  • geometry: 장소의 도형 관련 정보. 여기에는 다음 요소가 포함됩니다.
    • location은 장소의 위도와 경도를 제공합니다.
    • viewport는 이 장소를 지도에 표시할 때 표시되는 기본 표시 영역을 정의합니다.
  • permanently_closed(지원 중단됨)는 장소가 영구적으로 또는 일시적으로 폐점했는지 여부를 나타내는 불리언 플래그입니다(true 값). permanently_closed는 사용하지 마세요. 비즈니스의 영업 상태를 가져오려면 business_status를 대신 사용하세요.
  • plus_code(Open Location Code 및 Plus Code 참고)는 위도와 경도 좌표에서 파생된 인코딩된 위치 참조로 1/8000도x1/8000도(적도에서 14mx14m) 이하의 영역을 나타냅니다. Plus Code는 상세 주소가 없는 (건물에 번호가 지정되지 않거나 거리 이름이 없는) 장소의 상세 주소 대신 사용할 수 있습니다.

    Plus Code는 글로벌 코드 및 복합 코드로 형식이 지정됩니다.

    • global_code는 4자리 지역 코드와 6자 이상의 로컬 코드(849VCWC8+R9)입니다.
    • compound_code는 명시적인 위치가 포함된 6자 이상의 로컬 코드(CWC8+R9 Mountain View, CA, USA)입니다. 이 콘텐츠를 프로그래매틱 방식으로 파싱하지 마세요.
    일반적으로 글로벌 코드와 복합 코드가 모두 반환됩니다. 하지만 결과가 원격 위치(예: 바다 또는 사막)에 있는 경우에는 글로벌 코드만 반환될 수도 있습니다.
  • html_attributions: 검색 결과를 표시할 때 표시해야 저작자 표시의 배열입니다. 배열의 각 항목에는 단일 저작자 표시의 HTML 텍스트가 포함됩니다. 참고: 이 배열은 전체 검색 응답의 모든 저작자 표시를 집계한 것입니다. 따라서 응답의 모든 PlaceResult 객체에는 동일한 저작자 표시 목록이 포함됩니다.
  • icon은 색상이 지정된 71x71픽셀 PNG 아이콘의 URL을 반환합니다.
  • icon_mask_base_uri는 색상이 지정되지 않은 아이콘의 기본 URL에서 .svg 또는 .png 확장자를 뺀 값을 반환합니다.
  • icon_background_color는 장소 카테고리의 기본 16진수 색상 코드를 반환합니다.
  • name: 장소의 이름
  • opening_hours에는 다음 정보가 포함될 수 있습니다.
    • open_now는 장소가 현재 영업 중인지 여부를 나타내는 불리언 값입니다(Maps JavaScript API의 장소 라이브러리에서는 지원 중단되었습니다. utc_offset_minutes를 대신 사용하세요).
  • place_id는 장소를 고유하게 나타내는 텍스트 식별자입니다. 장소에 대한 정보를 가져오려면 장소 세부정보 요청에 이 식별자를 전달하세요. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.
  • rating에는 집계된 사용자 리뷰를 기준으로 한 장소 평점(0.0~5.0)이 포함됩니다.
  • types: 이 장소에 대한 유형의 배열(예: ["political", "locality"] 또는 ["restaurant", "lodging"]). 이 배열은 여러 값을 포함할 수도 있고 비어 있을 수도 있습니다. 사전 고지 없이 새로운 값이 도입될 수도 있습니다. 지원되는 유형의 목록을 참고하세요.
  • vicinity: 도로명, 번지, 지역은 포함하되 주/도, 우편번호, 국가는 포함되지 않은 장소의 단순화된 주소입니다. 예를 들어 Google 오스트레일리아 시드니 사무실의 vicinity 값은 5/48 Pirrama Road, Pyrmont입니다.

추가 결과 액세스

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

  • hasNextPage: 추가 결과를 사용할 수 있는지 여부를 나타내는 불리언 속성. 추가 결과 페이지가 있는 경우 true입니다.
  • nextPage(): 다음 결과 집합을 반환하는 함수. 검색을 실행한 후 2초를 기다려야 다음 결과 페이지를 사용할 수 있습니다.

다음 결과 집합을 보려면 nextPage를 호출하세요. 각 결과 페이지는 다음 결과 페이지를 표시하기 전에 표시해야 합니다. 각 검색은 사용량 한도 계산 시 하나의 요청으로 간주됩니다.

아래 예에서는 여러 번 검색을 요청할 수 있도록 콜백 함수를 변경하여 PlaceSearchPagination 객체를 캡처하는 방법을 보여줍니다.

TypeScript

// 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 initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// 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 initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
예 보기

샘플 사용해 보기

장소 세부정보

장소 서비스는 특정 지역 내 장소의 목록을 제공하는 것 외에 특정 장소에 대한 자세한 정보도 반환할 수 있습니다. 장소 검색 응답에 장소가 반환되면 장소 ID를 사용하여 전체 주소, 전화번호, 사용자 평점 및 리뷰 등 해당 장소에 대한 추가 세부정보를 요청할 수 있습니다.

장소 세부정보 요청

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

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

이 메서드는 원하는 장소의 placeId와 반환할 장소 데이터의 유형을 나타내는 필드가 포함된 요청을 받습니다. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.

또한 google.maps.places.PlacesServiceStatus 응답에 전달된 상태 코드 및 google.maps.places.PlaceResult 객체를 처리해야 하는 콜백 메서드를 받습니다.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

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

예 보기

필드(장소 세부정보)

fields 매개변수는 문자열의 배열(필드 이름)을 사용합니다.

fields 매개변수를 사용하여 반환할 장소 데이터 유형의 배열을 지정합니다. 예: fields: ['address_components', 'opening_hours', 'geometry']. 복합 값을 지정하려면 점을 사용하세요. 예: opening_hours.weekday_text

필드는 장소 세부정보 결과에 해당하며 기본, 연락처, 분위기 등 세 결제 카테고리로 분류됩니다. 기본 필드에는 기본 요율로 청구되며 추가 요금이 발생하지 않습니다. 연락처 및 분위기 필드에는 더 높은 요율로 청구됩니다. 자세한 내용은 가격표를 참고하세요. 저작자 표시(html_attributions)는 요청 여부에 관계없이 모든 호출에서 항상 반환됩니다.

기본

기본 카테고리에는 다음 필드가 포함됩니다.
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed(지원 중단됨), photo, place_id, plus_code, type, url, utc_offset(Maps JavaScript API의 장소 라이브러리에서는 지원 중단됨), utc_offset_minutes, vicinity

연락처

연락처 카테고리에는 다음 필드가 포함됩니다.
formatted_phone_number, international_phone_number, opening_hours, website

분위기

분위기 카테고리에는 다음 필드가 포함됩니다. price_level, rating, reviews, user_ratings_total

장소 필드에 대해 자세히 알아보세요. 장소 데이터 요청에 대해 요금이 청구되는 방법에 대한 자세한 내용은 사용량 및 결제를 참고하세요.

장소 세부정보 응답

상태 코드

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

  • INVALID_REQUEST: 잘못된 요청입니다.
  • OK: 응답에 유효한 결과가 포함되어 있습니다.
  • OVER_QUERY_LIMIT: 웹페이지가 요청 할당량을 초과했습니다.
  • NOT_FOUND: 참조된 위치를 장소 데이터베이스에서 찾을 수 없습니다.
  • REQUEST_DENIED: 웹페이지에서 PlacesService를 사용할 수 없습니다.
  • UNKNOWN_ERROR: 서버 오류로 인해 PlacesService 요청을 처리하지 못했습니다. 다시 시도하면 요청이 성공할 수도 있습니다.
  • ZERO_RESULTS: 이 요청에 대한 결과를 찾지 못했습니다.

장소 세부정보 결과

getDetails() 호출이 성공하면 다음과 같은 속성이 있는 PlaceResult 객체가 반환됩니다.

  • address_components: 이 주소에 적용할 수 있는 별도의 구성요소가 포함된 배열

    각 주소 구성요소에는 일반적으로 다음과 같은 필드가 포함됩니다.

    • types[]는 주소 구성요소의 유형을 나타내는 배열입니다. 지원되는 유형의 목록을 참고하세요.
    • long_name은 지오코더에서 반환하는 주소 구성요소의 전체 텍스트 설명 또는 이름입니다.
    • short_name은 주소 구성요소의 축약된 텍스트 이름입니다(해당하는 경우). 예를 들어 알래스카 주의 주소 구성요소에는 long_name 'Alaska'와 두 자리 우편 약어를 사용하는 short_name 'AK'가 포함될 수 있습니다.

    address_components[] 배열에 대한 다음 사실을 참고하세요.

    • 주소 구성요소의 배열에 formatted_address보다 더 많은 구성요소가 포함될 수도 있습니다.
    • formatted_address에 포함된 것 외에 주소가 포함된 모든 정치적 독립체가 배열에 포함되는 것은 아닙니다. 특정 주소가 포함된 모든 정치적 독립체를 가져오려면 역 지오코딩을 사용하여 주소의 위도/경도를 매개변수로 요청에 전달해야 합니다.
    • 응답의 형식이 요청 간에 동일하게 유지되지 않을 수도 있습니다. 특히 address_components의 수는 요청된 주소에 따라 다르며 동일한 주소에 대해서도 시간이 지남에 따라 변경될 수 있습니다. 배열에서 구성요소의 위치가 변경될 수 있습니다. 구성요소의 유형이 변경될 수 있습니다. 특정 구성요소가 이후 응답에서 누락될 수 있습니다.
  • business_status는 장소가 비즈니스인 경우 장소의 영업 상태를 나타냅니다. 다음 값 중 하나가 포함될 수 있습니다.
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    데이터가 없으면 business_status가 반환되지 않습니다.
  • formatted_address: 이 장소의 사람이 읽을 수 있는 주소

    이 주소는 대개 우편 주소와 일치합니다. 참고: 영국과 같은 일부 국가에서는 라이선스 제한으로 인해 실제 우편 주소의 배포가 허용되지 않습니다.

    형식이 지정된 주소는 하나 이상의 주소 구성요소로 논리적으로 구성됩니다. 예를 들어 주소 '111 8th Avenue, New York, NY'는 '111'(번지), '8th Avenue'(경로), 'New York'(도시) 및 'NY'(미국의 주)로 구성됩니다.

    형식이 지정된 주소를 프로그래매틱 방식으로 파싱하지 마세요. 대신 API 응답에 형식이 지정된 주소 필드 외에 포함되는 개별 주소 구성요소를 사용해야 합니다.

  • formatted_phone_number: 지역의 전화번호 규칙에 따라 형식이 지정된 장소의 전화번호
  • geometry: 장소의 도형 관련 정보. 여기에는 다음 요소가 포함됩니다.
    • location은 장소의 위도와 경도를 제공합니다.
    • viewport는 이 장소를 지도에 표시할 때 표시되는 기본 표시 영역을 정의합니다.
  • permanently_closed(지원 중단됨)는 장소가 영구적으로 또는 일시적으로 폐점했는지 여부를 나타내는 불리언 플래그입니다(true 값). permanently_closed는 사용하지 마세요. 비즈니스의 영업 상태를 가져오려면 business_status를 대신 사용하세요.
  • plus_code(Open Location Code 및 Plus Code 참고)는 위도와 경도 좌표에서 파생된 인코딩된 위치 참조로 1/8000도x1/8000도(적도에서 14mx14m) 이하의 영역을 나타냅니다. Plus Code는 상세 주소가 없는 (건물에 번호가 지정되지 않거나 거리 이름이 없는) 장소의 상세 주소 대신 사용할 수 있습니다.

    Plus Code는 글로벌 코드 및 복합 코드로 형식이 지정됩니다.

    • global_code는 4자리 지역 코드와 6자 이상의 로컬 코드(849VCWC8+R9)입니다.
    • compound_code는 명시적인 위치가 포함된 6자 이상의 로컬 코드(CWC8+R9 Mountain View, CA, USA)입니다. 이 콘텐츠를 프로그래매틱 방식으로 파싱하지 마세요.
    일반적으로 글로벌 코드와 복합 코드가 모두 반환됩니다. 하지만 결과가 원격 위치(예: 바다 또는 사막)에 있는 경우에는 글로벌 코드만 반환될 수도 있습니다.
  • html_attributions: 이 장소 결과에 대해 표시할 저작자 표시 텍스트
  • icon: 이 장소의 유형을 나타내는 데 사용할 수 있는 이미지 리소스의 URL
  • international_phone_number에는 장소의 전화번호가 국가 코드 포함 형식으로 포함됩니다. 국가 코드 포함 형식에는 국가 코드가 포함되며 앞에 더하기(+) 기호가 붙습니다. 예를 들어 Google의 오스트레일리아 시드니 사무실의 international_phone_number는 +61 2 9374 4000입니다.
  • name: 장소의 이름
  • utc_offset: Maps JavaScript API의 장소 라이브러리에서는 지원 중단되었습니다. utc_offset_minutes를 대신 사용하세요.
  • utc_offset_minutes: 이 장소의 현재 시간대와 UTC의 시간차가 분 단위로 포함됩니다. 예를 들어 일광 절약 시간이 적용된 오스트레일리아 시드니에 있는 장소의 경우 660(UTC에서 +11시간), 일광 절약 시간이 적용되지 않은 캘리포니아에 있는 장소의 경우 -480(UTC에서 -8시간)입니다.
  • opening_hours에는 다음 정보가 포함됩니다.
    • open_now(Maps JavaScript API의 장소 라이브러리에서는 지원 중단되었습니다. opening_hours.isOpen()을 대신 사용하세요. isOpen을 장소 세부정보와 함께 사용하는 방법은 이 동영상을 참고하세요.)는 장소가 현재 영업 중인지 여부를 나타내는 불리언 값입니다.
    • periods[]는 일요일부터 7일 동안의 영업 기간을 시간순으로 나타내는 배열입니다. 각 기간에는 다음 항목이 포함됩니다.
      • open에는 장소의 개점 시간을 나타내는 요일 및 시간 객체 쌍이 포함됩니다.
        • day: 요일에 해당하는 0~6 사이의 숫자이며 일요일부터 시작됩니다. 예를 들어 2는 화요일을 의미합니다.
        • time에는 하루 중 시간이 24시간 hhmm 형식으로 포함될 수 있으며 값의 범위는 0000~2359입니다. time은 장소의 시간대로 보고됩니다.
      • close에는 장소의 폐점 시간을 나타내는 요일 및 시간 객체 쌍이 포함됩니다. 참고: 장소가 항상 열려 있는 경우 응답에서 close 섹션이 누락됩니다. 애플리케이션에서는 항상 열려 있음을 값이 0인 day를 포함한 open 기간, 값이 0000인 time 그리고 close 없음으로 표시할 수 있습니다.
    • weekday_text는 각 요일의 형식이 지정된 영업시간을 나타내는 일곱 개 문자열의 배열입니다. 장소 세부정보 요청에 language 매개변수가 지정된 경우 Place Service는 해당 언어에 맞게 영업시간의 형식을 지정하고 현지화합니다. 이 배열에서 요소의 순서는 language 매개변수에 따라 다릅니다. 일부 언어에서는 월요일에 한 주를 시작하고 다른 언어에서는 일요일에 시작합니다.
  • permanently_closed(지원 중단됨)는 장소가 영구적으로 또는 일시적으로 폐점했는지 여부를 나타내는 불리언 플래그입니다(true 값). permanently_closed는 사용하지 마세요. 비즈니스의 영업 상태를 가져오려면 business_status를 대신 사용하세요.
  • photos[]: PlacePhoto 객체의 배열. PlacePhoto는 getUrl() 메서드로 사진을 가져오는 데 사용할 수 있습니다. 또는 객체에서 다음 값을 검사할 수 있습니다.
    • height: 이미지의 최대 높이(픽셀)
    • width: 이미지의 최대 너비(픽셀)
    • html_attributions: 이 장소 사진과 함께 표시할 저작자 표시 텍스트
  • place_id: 장소를 고유하게 나타내며 장소 세부정보 요청을 통해 장소에 관한 정보를 가져오는 데 사용할 수 있는 텍스트 식별자입니다. 장소 ID로 장소를 참조하는 방법에 대해 자세히 알아보세요.
  • rating: 집계된 사용자 리뷰를 기준으로 한 장소 평점(0.0~5.0)
  • reviews: 최대 다섯 개 리뷰의 배열. 각 리뷰는 여러 구성요소로 구성됩니다.
    • aspects[]에는 PlaceAspectRating 객체의 배열이 포함됩니다. 각 객체는 시설의 단일 속성의 평가를 제공합니다. 배열의 첫 번째 객체가 기본 측면으로 간주됩니다. 각 PlaceAspectRating은 다음과 같이 정의됩니다.
      • type: 평가되는 측면의 이름. 다음 유형이 지원됩니다. appeal, atmosphere, decor, facilities, food, overall, quality, service
      • rating: 이 특정 측면에 대한 사용자 평점(0~3)
    • author_name: 리뷰를 제출한 사용자의 이름. 익명의 리뷰는 'A Google user'로 저작자가 표시됩니다. 언어 매개변수가 설정된 경우 'A Google user' 문구가 현지화된 문자열로 반환됩니다.
    • 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. 장소에 대한 최상의 정보가 포함된 Google 소유 페이지입니다. 애플리케이션에서는 장소에 대한 자세한 결과를 사용자에게 표시하는 모든 화면에 이 페이지를 연결하거나 포함해야 합니다.
  • vicinity: 도로명, 번지, 지역은 포함하되 주/도, 우편번호, 국가는 포함되지 않은 장소의 단순화된 주소입니다. 예를 들어 Google 오스트레일리아 시드니 사무실의 vicinity 값은 5/48 Pirrama Road, Pyrmont입니다. vicinity 속성은 주변 검색의 경우에만 반환됩니다.
  • website는 비즈니스 홈페이지와 같이 이 장소의 신뢰할 수 있는 웹사이트를 표시합니다.

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

장소 ID로 장소 참조

장소 ID는 Google 지도의 장소에 대한 고유한 참조입니다. 장소 ID는 비즈니스, 명소, 공원, 교차로 등 대부분의 위치에 사용할 수 있습니다.

앱에서 장소 ID를 사용하려면 먼저 장소 검색 또는 세부정보 요청의 PlaceResult에서 사용할 수 있는 ID를 조회해야 합니다. 그런 다음 이 장소 ID를 사용하여 장소 세부정보를 조회할 수 있습니다.

장소 ID에는 Google Maps Platform 서비스 약관의 3.2.3(b)항에 명시된 캐싱 제한사항이 적용되지 않습니다. 따라서 나중에 사용하기 위해 장소 ID 값을 저장할 수 있습니다. 장소 ID를 저장할 때의 권장사항은 장소 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+ 로컬 데이터베이스에 저장된 수백만 장의 사진에 액세스할 수 있습니다. 장소 세부정보 요청을 사용하여 장소 정보를 가져오면 관련 사진 콘텐츠에 대해 사진 참조가 반환됩니다. 주변 검색 및 텍스트 검색 요청도 관련된 경우 장소당 하나의 사진 참조를 반환합니다. 그런 다음 사진 서비스를 사용하여 참조된 사진에 액세스하고 이미지를 애플리케이션에 가장 적합한 크기로 조정할 수 있습니다.

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

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

  • 주변 검색 또는 텍스트 검색은 최대 한 개의 PlacePhoto 객체를 반환합니다.
  • 세부정보 요청은 최대 열 개의 PlacePhoto 객체를 반환합니다.

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

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

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})
  });
}

사진 서비스에서 반환되는 사진은 비즈니스 소유자 및 사용자 제공 사진을 비롯한 다양한 위치에서 가져온 것입니다. 대부분의 경우 이러한 사진은 저작자 표시 없이 사용할 수 있거나 필수 저작권 표시가 이미지의 일부로 포함되어 있습니다. 하지만 반환된 photo 요소의 html_attributions 필드에 값이 포함된 경우 이미지를 표시할 때마다 애플리케이션에 추가 저작자 표시를 포함해야 합니다.