이전에 Places Insights API라고 했던 Places Aggregate API가 이제 정식 버전 (GA)으로 제공됩니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

요청 매개변수

이 문서에서는 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: 아파트, 유닛, 스위트룸과 같이 구내 수준 아래의 주소 지정 가능 항목을 나타냅니다.

참고: 위에 나열되지 않은 일부 장소도 잘 정의된 다각형 지오메트리가 없으면 거부될 수 있습니다. 이 문제는 neighborhood, locality, sublocality와 번호가 지정된 변형(sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4)과 같은 유형에서 더 흔하게 발생합니다. 이 경우 400 오류 코드가 반환됩니다.

맞춤 영역

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

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: 제외된 기본 장소 유형 목록입니다.

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

선택적 매개변수

다음 필터는 선택사항입니다.

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 오류가 반환됩니다.