요청 매개변수

이 문서에서는 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%).

장소 ID가 지원되지 않는 장소 유형을 나타내는지 확인하려면 장소 ID를 Geocoding API 요청에서 전달합니다. 응답에는 장소 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 (신규)의 장소 유형 아래 표 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 오류가 반환됩니다.