Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

요청 매개변수

이 문서에서는 Places Aggregate API의 요청 매개변수를 설명하고 이 서비스를 사용하기 위한 유용한 정보와 권장사항을 제공합니다.

Places Aggregate API를 사용하면 다음과 같은 몇 가지 주요 기능을 수행할 수 있습니다.

장소 수 세기: 위치 유형, 영업 상태, 가격대, 평점과 같은 특정 기준에 부합하는 장소의 수를 확인합니다.
장소 세부정보 가져오기: 지정된 필터를 충족하는 장소의 이름을 가져온 다음 Places API를 사용하여 더 자세한 정보를 가져옵니다.
유연한 필터링: 포괄적인 필터를 적용하여 정확한 집계를 얻을 수 있습니다. 사용 가능한 필터는 다음과 같습니다.
- 지리적 영역 (원, 지역 또는 맞춤 다각형)
- 장소 유형
- 영업 상태
- 가격 수준
- 등급 범위

필수 매개변수

이 섹션에서는 Places Aggregate API에 요청을 보낼 때 필요한 매개변수를 설명합니다. 각 요청은 다음을 제공해야 합니다.

통계 유형입니다.
위치 필터 및 유형 필터입니다.

통계 유형

계산할 통계 유형을 지정합니다. 지원되는 통계 유형은 다음과 같습니다.

INSIGHT_COUNT: 필터 기준과 일치하는 장소 수를 반환합니다.
INSIGHT_PLACES: 필터 기준과 일치하는 장소 ID를 반환합니다.

필터

장소를 필터링하기 위한 기준을 지정합니다. 최소한 LocationFilter 및 TypeFilter를 지정해야 합니다.

위치 필터

위치 필터는 다음 유형 중 하나일 수 있습니다.

circle: 중심과 반지름이 있는 원으로 영역을 정의합니다.
region: 영역을 리전으로 정의합니다.
customArea: 영역을 맞춤 다각형으로 정의합니다.

원

지리적 영역을 원으로 선택하는 경우 center 및 radius를 제공해야 합니다. center는 위도 및 경도이거나 원 중심의 장소 ID일 수 있습니다. 이 방법을 사용하면 정의된 원형 영역을 기반으로 정확하게 필터링할 수 있습니다.

center:
- latLng: 원 중심의 위도 및 경도입니다. 위도는 -90에서 90 사이의 숫자여야 합니다(포함). 경도는 -180에서 180 사이의 숫자여야 합니다.
- place: 원 중심의 장소 ID입니다. 포인트 장소만 지원됩니다. 이 문자열은 places/ 접두사로 시작해야 합니다.
radius: 원의 반경(미터)입니다. 이 숫자는 양수여야 합니다.

리전

장소 ID를 place 매개변수에 전달하여 지역을 정의합니다. 장소 ID는 지리적 영역 (예: 다각형으로 나타낼 수 있는 영역)을 나타냅니다. 예를 들어 플로리다주 탬파의 장소 ID는 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c입니다. 모든 장소 ID에 명확하게 정의된 도형이 있는 것은 아니며, 이 경우 Places Aggregate API는 지역이 지원되지 않는다는 메시지와 함께 400 오류 코드를 반환합니다. 또한 복잡한 지리적 리전의 경우 내부 처리 최적화로 인해 리전을 나타내는 영역이 약간 과대 근사 (최대 2~3%)될 수 있습니다.

중요: INSIGHT_PLACES 통계 유형과 함께 region 필터를 사용하는 경우 Google 서비스의 정확성과 중립성을 보장하기 위해 분쟁 지역이 포함된 요청은 자동으로 거부됩니다. 분쟁 지역은 서로 다른 국가 또는 단체 간에 경계 또는 영토 소유권 주장이 충돌하는 지역입니다. 분쟁 지역의 경계선은 Google 지도에 회색 파선으로 표시됩니다.

분쟁 지역이 식별되는 방식에 대한 자세한 내용은 국경 및 국가 이름 이해하기를 참고하세요.

장소 ID가 지원되지 않는 장소 유형을 나타내는지 확인하려면 Geocoding API 요청에 장소 ID를 전달하세요. 응답에는 장소 ID와 연결된 장소 유형(예: locality, neighborhood, country)을 나열하는 type 배열이 포함됩니다. 유형 중 하나라도 이 목록과 일치하면 지역 필터링으로 인해 장소가 거부됩니다.

지원되지 않는 장소 유형은 다음과 같습니다.

establishment: 일반적으로 아직 분류되지 않은 장소를 나타냅니다.
intersection: 주요 교차로(일반적으로 두 주요 도로)를 나타냅니다.
subpremise: 아파트, 단위, 스위트룸과 같이 구내 수준 아래의 주소 지정 가능 항목을 나타냅니다.

맞춤 영역

위도 및 경도 좌표를 사용하여 맞춤 다각형의 영역을 정의합니다.

https://geojson.io/를 방문하여 커스텀 다각형을 그리고 해당 좌표를 요청에 입력할 수 있습니다. 다각형에는 최소 4개의 좌표가 있어야 하며 첫 번째 좌표와 마지막 좌표는 동일해야 합니다. 제공된 좌표 중 3개 이상이 고유해야 합니다.

연속적으로 동일한 좌표는 단일 좌표로 처리됩니다. 하지만 연속되지 않은 중복 좌표 (필수 동일 첫 번째 및 마지막 좌표 제외)는 오류를 일으킵니다.

또한 인접하지 않은 모서리는 교차할 수 없으며 길이가 180도인 모서리는 허용되지 않습니다 (즉, 인접한 꼭짓점은 반대편에 있을 수 없음).

예를 들면 다음과 같습니다.

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

유형 필터

포함하거나 제외할 장소 유형을 지정합니다. Places Aggregate API에서 지원하는 기본 및 보조 장소 유형 목록은 Places API(New)의 장소 유형에 있는 표 A를 참고하세요. includedTypes 또는 includedPrimaryTypes 유형을 하나 이상 지정해야 합니다.

includedTypes: 포함된 장소 유형 목록
excludedTypes: 제외된 장소 유형 목록입니다.
includedPrimaryTypes: 포함된 기본 장소 유형 목록입니다.
excludedPrimaryTypes: 제외된 기본 장소 유형 목록입니다.

유형 필터와 장소 유형의 작동 방식에 대해 자세히 알아보려면 유형 필터 자세히 알아보기를 참고하세요.

참고: 유형 필터에는 지정된 유형의 하위 유형이 자동으로 포함됩니다. 예를 들어 gym로 필터링하면 yoga_studio와 같은 하위 유형으로 분류된 장소도 결과에 포함됩니다.

선택적 매개변수

이러한 필터는 선택사항입니다.

operatingStatus: 포함하거나 제외할 장소의 상태를 지정합니다. 기본적으로 operatingStatus: OPERATING_STATUS_OPERATIONAL(하나의 특정 값)을 기준으로 필터링됩니다.
priceLevels: 포함할 장소의 가격대를 지정합니다. 기본적으로 가격대 필터링이 적용되지 않으며 가격대 정보가 없는 장소를 포함한 모든 장소가 반환됩니다.
ratingFilter: 장소의 평가 범위를 지정합니다. 기본값은 필터링 없음 (모든 등급이 결과에 포함됨)입니다.

영업 상태

operatingStatus 필터를 사용하면 OPERATIONAL 또는 TEMPORARILY_CLOSED와 같은 영업 상태를 기준으로 필터링할 수 있습니다. operatingStatus 필터 동작은 다음과 같이 작동합니다.

필터가 제공되지 않으면 운영 상태가 OPERATING_STATUS_OPERATIONAL인 장소만 결과에 포함됩니다.
하나 이상의 필터가 제공된 경우 유효한 영업 상태 값 (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED 또는 OPERATING_STATUS_TEMPORARILY_CLOSED)을 지정해야 합니다.

가격 수준

priceLevels 필터를 사용하면 가격 수준을 기준으로 장소를 필터링할 수 있습니다. 유효한 가격 수준 값은 PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, PRICE_LEVEL_VERY_EXPENSIVE입니다.

priceLevels 필터의 동작은 다음과 같습니다.

필터가 제공되지 않은 경우: 가격대가 할당되었는지 여부와 관계없이 모든 장소가 반환됩니다. 여기에는 가격 수준 정보가 없는 장소가 포함되며, 특정 가격 수준으로 필터링할 때는 반환되지 않을 수 있습니다.
필터가 하나 이상 제공된 경우: 지정된 가격대와 일치하는 장소만 반환됩니다.

평점 필터

평균 사용자 평점을 기준으로 장소를 필터링합니다. 이 두 필드는 모두 선택사항이므로 생략하면 등급이 없는 장소도 포함하도록 기본값이 설정됩니다.

minRating: 최소 평균 사용자 평점 (1.0~5.0)
maxRating: 최대 평균 사용자 평점 (1.0~5.0)

또한 minRating 값은 항상 maxRating 값보다 작거나 같아야 합니다. minRating이 maxRating보다 큰 것으로 지정되면 INVALID_ARGUMENT 오류가 반환됩니다.